From 8d4e523df8b16b5afa8d9f927b0657472a704f64 Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 15:35:22 -0300
Subject: [PATCH 1/8] docs(ui): document the non-atomic provider change window

Changing an SSO provider deletes the existing enterprise connection before
creating the new one. Document that this is intentionally non-atomic for the
MVP: a failed create briefly leaves the org without a connection, and recovery
is by design since the next render revalidates the deleted connection away so a
retry becomes a plain create.
---
 .../hooks/useOrganizationEnterpriseConnection.ts           | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/ConfigureSSO/hooks/useOrganizationEnterpriseConnection.ts b/packages/ui/src/components/ConfigureSSO/hooks/useOrganizationEnterpriseConnection.ts
index 024c35a15c9..c9cdd7090fb 100644
--- a/packages/ui/src/components/ConfigureSSO/hooks/useOrganizationEnterpriseConnection.ts
+++ b/packages/ui/src/components/ConfigureSSO/hooks/useOrganizationEnterpriseConnection.ts
@@ -228,8 +228,11 @@ export const useOrganizationEnterpriseConnection = (): UseOrganizationEnterprise
     };
 
     const changeProvider: EnterpriseConnectionMutations['changeProvider'] = async provider => {
-      // Currently it's not possible to change the provider of an existing connection,
-      // so we need to delete the existing connection and create a new one.
+      // FAPI can't switch an existing connection's provider in place, so for the MVP
+      // we delete the old connection and create a new one. This is intentionally
+      // non-atomic: if the create fails, the org is briefly left without a connection
+      // until the user retries. Recovery is by design — the next render revalidates
+      // the now-deleted connection away, so a retry is just a plain create.
       if (enterpriseConnection) {
         await deleteEnterpriseConnection(enterpriseConnection.id);
       }

From e4693cec5af0d8c68e26ceaa809158d47a0759f9 Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 15:35:30 -0300
Subject: [PATCH 2/8] fix(ui): keep change-provider dialog open on failure and
 make it accessible

A failed provider change now surfaces the error inline inside the dialog via the
shared card state, keeping the dialog open so the user can retry or cancel
instead of dropping the error behind a dismissed modal. The dialog also gains an
accessible name (aria-labelledby wired to its heading) and restores
Escape-to-close (ignored while a change is in progress). Threads
aria-labelledby/aria-label and onKeyDown through the Modal primitive onto the
role=dialog node.
---
 .../ConfigureSSO/ChangeProviderDialog.tsx     | 163 +++++++++++-------
 packages/ui/src/elements/Modal.tsx            |  24 ++-
 2 files changed, 124 insertions(+), 63 deletions(-)

diff --git a/packages/ui/src/components/ConfigureSSO/ChangeProviderDialog.tsx b/packages/ui/src/components/ConfigureSSO/ChangeProviderDialog.tsx
index 44623de0505..9a064a014c9 100644
--- a/packages/ui/src/components/ConfigureSSO/ChangeProviderDialog.tsx
+++ b/packages/ui/src/components/ConfigureSSO/ChangeProviderDialog.tsx
@@ -1,14 +1,18 @@
+import { useId, useState } from 'react';
+
 import type { LocalizationKey } from '@/customizables';
 import { Button, Col, descriptors, Flex, Heading, localizationKeys, Text, useLocalizations } from '@/customizables';
 import { Card } from '@/elements/Card';
-import { withCardStateProvider } from '@/elements/contexts';
+import { useCardState, withCardStateProvider } from '@/elements/contexts';
 import { Modal } from '@/elements/Modal';
+import { Alert } from '@/ui/elements/Alert';
+import { handleError } from '@/utils/errorHandler';
 
 type ChangeProviderDialogProps = {
   isOpen: boolean;
   onClose: () => void;
-  onConfirm: () => void;
-  isSubmitting?: boolean;
+  /** Performs the provider change. Rejecting keeps the dialog open with the error shown inline. */
+  onConfirm: () => Promise<unknown>;
   nextProviderLabel: LocalizationKey;
   currentProviderLabel: LocalizationKey;
   contentRef: React.RefObject<HTMLDivElement>;
@@ -19,11 +23,52 @@ export const ChangeProviderDialog = (props: ChangeProviderDialogProps): JSX.Elem
     return null;
   }
 
+  return <ChangeProviderDialogContent {...props} />;
+};
+
+const ChangeProviderDialogContent = withCardStateProvider((props: ChangeProviderDialogProps) => {
+  const { onClose, onConfirm, nextProviderLabel, currentProviderLabel, contentRef } = props;
+  const { t } = useLocalizations();
+  const card = useCardState();
+
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const titleId = useId();
+
+  const nextProvider = t(nextProviderLabel);
+  const currentProvider = t(currentProviderLabel);
+
+  const handleConfirm = async () => {
+    card.setError(undefined);
+    setIsSubmitting(true);
+
+    try {
+      // On success the wizard advances and unmounts this dialog; on failure we
+      // surface the error inline and keep the dialog open so the user can retry.
+      await onConfirm();
+    } catch (err) {
+      handleError(err as Error, [], card.setError);
+      setIsSubmitting(false);
+    }
+  };
+
+  const handleClose = () => {
+    if (isSubmitting) {
+      return;
+    }
+    onClose();
+  };
+
   return (
     <Modal
-      handleClose={props.onClose}
+      handleClose={onClose}
       canCloseModal={false}
-      portalRoot={props.contentRef}
+      portalRoot={contentRef}
+      aria-labelledby={titleId}
+      onKeyDown={event => {
+        if (event.key === 'Escape') {
+          handleClose();
+        }
+      }}
       containerSx={t => ({
         alignItems: 'center',
         position: 'absolute',
@@ -34,64 +79,60 @@ export const ChangeProviderDialog = (props: ChangeProviderDialogProps): JSX.Elem
         backdropFilter: `blur(${t.sizes.$2})`,
       })}
     >
-      <ChangeProviderDialogContent {...props} />
-    </Modal>
-  );
-};
-
-const ChangeProviderDialogContent = withCardStateProvider((props: ChangeProviderDialogProps) => {
-  const { onClose, onConfirm, isSubmitting, nextProviderLabel, currentProviderLabel } = props;
-  const { t } = useLocalizations();
+      <Card.Root
+        elementDescriptor={descriptors.configureSSOChangeProviderDialog}
+        sx={t => ({ borderRadius: t.radii.$md })}
+      >
+        <Card.Content sx={t => ({ textAlign: 'start', padding: t.sizes.$5 })}>
+          <Col sx={t => ({ gap: t.space.$4 })}>
+            <Col sx={t => ({ gap: t.space.$2 })}>
+              <Heading
+                id={titleId}
+                textVariant='h2'
+                localizationKey={localizationKeys('configureSSO.changeProviderDialog.title', {
+                  provider: nextProvider,
+                })}
+                sx={t => ({ fontSize: t.fontSizes.$md })}
+              />
+              <Text
+                as='p'
+                colorScheme='secondary'
+                localizationKey={localizationKeys('configureSSO.changeProviderDialog.subtitle', {
+                  provider: nextProvider,
+                  currentProvider,
+                })}
+              />
+            </Col>
 
-  const nextProvider = t(nextProviderLabel);
-  const currentProvider = t(currentProviderLabel);
+            {card.error && (
+              <Alert
+                variant='danger'
+                title={card.error}
+              />
+            )}
 
-  return (
-    <Card.Root
-      elementDescriptor={descriptors.configureSSOChangeProviderDialog}
-      sx={t => ({ borderRadius: t.radii.$md })}
-    >
-      <Card.Content sx={t => ({ textAlign: 'start', padding: t.sizes.$5 })}>
-        <Col sx={t => ({ gap: t.space.$4 })}>
-          <Col sx={t => ({ gap: t.space.$2 })}>
-            <Heading
-              textVariant='h2'
-              localizationKey={localizationKeys('configureSSO.changeProviderDialog.title', {
-                provider: nextProvider,
-              })}
-              sx={t => ({ fontSize: t.fontSizes.$md })}
-            />
-            <Text
-              as='p'
-              colorScheme='secondary'
-              localizationKey={localizationKeys('configureSSO.changeProviderDialog.subtitle', {
-                provider: nextProvider,
-                currentProvider,
-              })}
-            />
+            <Flex
+              justify='end'
+              sx={t => ({ gap: t.space.$3 })}
+            >
+              <Button
+                elementDescriptor={descriptors.configureSSOChangeProviderDialogCancelButton}
+                variant='ghost'
+                isDisabled={isSubmitting}
+                onClick={handleClose}
+                localizationKey={localizationKeys('configureSSO.changeProviderDialog.cancelButton')}
+              />
+              <Button
+                elementDescriptor={descriptors.configureSSOChangeProviderDialogConfirmButton}
+                variant='solid'
+                isLoading={isSubmitting}
+                onClick={() => void handleConfirm()}
+                localizationKey={localizationKeys('configureSSO.changeProviderDialog.confirmButton')}
+              />
+            </Flex>
           </Col>
-
-          <Flex
-            justify='end'
-            sx={t => ({ gap: t.space.$3 })}
-          >
-            <Button
-              elementDescriptor={descriptors.configureSSOChangeProviderDialogCancelButton}
-              variant='ghost'
-              isDisabled={isSubmitting}
-              onClick={onClose}
-              localizationKey={localizationKeys('configureSSO.changeProviderDialog.cancelButton')}
-            />
-            <Button
-              elementDescriptor={descriptors.configureSSOChangeProviderDialogConfirmButton}
-              variant='solid'
-              isLoading={isSubmitting}
-              onClick={onConfirm}
-              localizationKey={localizationKeys('configureSSO.changeProviderDialog.confirmButton')}
-            />
-          </Flex>
-        </Col>
-      </Card.Content>
-    </Card.Root>
+        </Card.Content>
+      </Card.Root>
+    </Modal>
   );
 });
diff --git a/packages/ui/src/elements/Modal.tsx b/packages/ui/src/elements/Modal.tsx
index 35ac4d9563a..36faccaca86 100644
--- a/packages/ui/src/elements/Modal.tsx
+++ b/packages/ui/src/elements/Modal.tsx
@@ -21,12 +21,29 @@ type ModalProps = React.PropsWithChildren<{
   style?: React.CSSProperties;
   portalRoot?: HTMLElement | React.MutableRefObject<HTMLElement | null>;
   initialFocusRef?: number | React.MutableRefObject<HTMLElement | null>;
+  /** Names the `role='dialog'` content node for assistive technology. */
+  'aria-labelledby'?: string;
+  'aria-label'?: string;
+  /** Forwarded to the dialog content node, e.g. to restore Escape-to-close. */
+  onKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
 }>;
 
 export const Modal = withFloatingTree((props: ModalProps) => {
   const { disableScrollLock, enableScrollLock } = useScrollLock();
-  const { handleClose, handleOpen, contentSx, containerSx, canCloseModal, id, style, portalRoot, initialFocusRef } =
-    props;
+  const {
+    handleClose,
+    handleOpen,
+    contentSx,
+    containerSx,
+    canCloseModal,
+    id,
+    style,
+    portalRoot,
+    initialFocusRef,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-label': ariaLabel,
+    onKeyDown,
+  } = props;
   const portalRootFromContext = usePortalRoot();
   const overlayRef = useRef<HTMLDivElement>(null);
   const { floating, isOpen, context, nodeId, toggle } = usePopover({
@@ -93,6 +110,9 @@ export const Modal = withFloatingTree((props: ModalProps) => {
             ref={floating}
             aria-modal='true'
             role='dialog'
+            aria-labelledby={ariaLabelledBy}
+            aria-label={ariaLabel}
+            onKeyDown={onKeyDown}
             sx={[
               t => ({
                 position: 'relative',

From e8e97a8ec05fe63db9ec6daac14366bb559646ad Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 15:35:47 -0300
Subject: [PATCH 3/8] fix(ui): restore accessible native radio cards in SSO
 provider step

Replace the role=radio buttons with the established radio-card pattern: a
visually hidden native radio inside a label, with the selected and focus styling
driven by :has(input:checked) and :has(input:focus-visible). This restores
native radiogroup keyboard semantics (arrow-key navigation and roving tabindex)
that role=radio on a button drops, while keeping the visible radio dot removed
per the design. The radio stays in the accessibility tree (sr-only, not
display:none) and names itself from the wrapping label.

Also wires the change-provider dialog to own its submit/error state so the step
re-throws on failure, and adds coverage for the inline error, Escape-to-close,
and the dialog's accessible name.
---
 .../ConfigureSSO/steps/SelectProviderStep.tsx | 77 +++++++++++--------
 .../__tests__/SelectProviderStep.test.tsx     | 56 +++++++++++++-
 2 files changed, 99 insertions(+), 34 deletions(-)

diff --git a/packages/ui/src/components/ConfigureSSO/steps/SelectProviderStep.tsx b/packages/ui/src/components/ConfigureSSO/steps/SelectProviderStep.tsx
index 383e47851e4..d5c27d0658f 100644
--- a/packages/ui/src/components/ConfigureSSO/steps/SelectProviderStep.tsx
+++ b/packages/ui/src/components/ConfigureSSO/steps/SelectProviderStep.tsx
@@ -2,7 +2,18 @@ import { iconImageUrl } from '@clerk/shared/constants';
 import React from 'react';
 
 import type { LocalizationKey } from '@/customizables';
-import { Box, Col, descriptors, Flow, Grid, localizationKeys, Span, Text, useLocalizations } from '@/customizables';
+import {
+  Box,
+  Col,
+  descriptors,
+  Flow,
+  Grid,
+  localizationKeys,
+  RadioInput,
+  Span,
+  Text,
+  useLocalizations,
+} from '@/customizables';
 import { useCardState } from '@/elements/contexts';
 import { common, mqu } from '@/styledSystem';
 import { Alert } from '@/ui/elements/Alert';
@@ -97,23 +108,16 @@ export const SelectProviderStep = (): JSX.Element => {
     }
   };
 
+  // The dialog owns its own submit/error state so a failed change stays visible
+  // inside the dialog and is retryable. We re-throw so the dialog can surface the
+  // error inline; on success goNext unmounts this step (and the dialog with it).
   const handleConfirmChangeProvider = async (): Promise<void> => {
     if (!selected) {
       return;
     }
 
-    card.setError(undefined);
-    setIsSubmitting(true);
-
-    try {
-      await changeProvider(selected);
-      void goNext();
-    } catch (err) {
-      handleError(err as Error, [], card.setError);
-      setIsChangeDialogOpen(false);
-      setChangeFromProvider(null);
-      setIsSubmitting(false);
-    }
+    await changeProvider(selected);
+    void goNext();
   };
 
   const currentProviderLabel = changeFromProvider ? providerLabel(changeFromProvider) : undefined;
@@ -162,11 +166,12 @@ export const SelectProviderStep = (): JSX.Element => {
                   {group.options.map(option => (
                     <ProviderCard
                       key={option.id}
+                      name='configure-sso-provider'
                       value={option.id}
                       iconId={option.iconId}
                       label={option.label}
-                      isSelected={selected === option.id}
-                      onSelect={() => handleSelect(option.id)}
+                      checked={selected === option.id}
+                      onChange={() => handleSelect(option.id)}
                     />
                   ))}
                 </Grid>
@@ -203,10 +208,7 @@ export const SelectProviderStep = (): JSX.Element => {
               setIsChangeDialogOpen(false);
               setChangeFromProvider(null);
             }}
-            onConfirm={() => {
-              void handleConfirmChangeProvider();
-            }}
-            isSubmitting={isSubmitting}
+            onConfirm={handleConfirmChangeProvider}
             nextProviderLabel={nextProviderLabel}
             currentProviderLabel={currentProviderLabel}
             contentRef={contentRef}
@@ -218,27 +220,24 @@ export const SelectProviderStep = (): JSX.Element => {
 };
 
 type ProviderCardProps = {
+  name: string;
   value: string;
   iconId: string;
   label: LocalizationKey;
-  isSelected?: boolean;
-  onSelect: () => void;
+  checked?: boolean;
+  onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
 };
 
-const ProviderCard = ({ value, iconId, label, isSelected, onSelect }: ProviderCardProps): JSX.Element => {
+const ProviderCard = ({ name, value, iconId, label, checked, onChange }: ProviderCardProps): JSX.Element => {
   const { t } = useLocalizations();
   const labelText = t(label);
 
   return (
     <Box
-      as='button'
-      role='radio'
-      aria-checked={isSelected}
-      aria-label={labelText}
+      as='label'
       elementDescriptor={descriptors.configureSSOProviderCard}
       elementId={descriptors.configureSSOProviderCard.setId(value)}
-      isActive={isSelected}
-      onClick={onSelect}
+      isActive={checked}
       sx={t => ({
         display: 'flex',
         flexDirection: 'column',
@@ -249,19 +248,33 @@ const ProviderCard = ({ value, iconId, label, isSelected, onSelect }: ProviderCa
         padding: t.space.$1x5,
         cursor: 'pointer',
         position: 'relative',
-        appearance: 'none',
-        textAlign: 'center',
-        backgroundColor: isSelected ? t.colors.$neutralAlpha50 : 'transparent',
         ...common.borderVariants(t).normal,
-        '&:focus-visible': {
+        '&:has(input:focus-visible)': {
           ...common.focusRingStyles(t),
           borderColor: t.colors.$borderAlpha300,
         },
         '&:hover': {
           backgroundColor: t.colors.$neutralAlpha50,
         },
+        '&:has(input:checked)': {
+          backgroundColor: t.colors.$neutralAlpha50,
+        },
       })}
     >
+      <RadioInput
+        elementDescriptor={descriptors.configureSSOProviderCardRadio}
+        elementId={descriptors.configureSSOProviderCardRadio.setId(value)}
+        name={name}
+        value={value}
+        checked={checked}
+        onChange={onChange}
+        focusRing={false}
+        // The visible dot is intentionally dropped per design; the radio stays in
+        // the a11y tree (sr-only, not display:none) so it keeps native radiogroup
+        // keyboard semantics and names itself from the wrapping label.
+        sx={common.visuallyHidden()}
+      />
+
       <Span
         elementDescriptor={descriptors.configureSSOProviderCardIcon}
         elementId={descriptors.configureSSOProviderCardIcon.setId(value)}
diff --git a/packages/ui/src/components/ConfigureSSO/steps/__tests__/SelectProviderStep.test.tsx b/packages/ui/src/components/ConfigureSSO/steps/__tests__/SelectProviderStep.test.tsx
index 3abd2d2f98a..1ec72e533bf 100644
--- a/packages/ui/src/components/ConfigureSSO/steps/__tests__/SelectProviderStep.test.tsx
+++ b/packages/ui/src/components/ConfigureSSO/steps/__tests__/SelectProviderStep.test.tsx
@@ -89,8 +89,10 @@ describe('SelectProviderStep', () => {
     const { wrapper } = await createFixtures();
     const { container } = renderStep(wrapper);
 
-    // Emotion serializes sx into stylesheets, so we check both inline + the document's collected styles
-    const iconSpans = Array.from(container.querySelectorAll('[role="radio"] span[aria-hidden]'));
+    // Emotion serializes sx into stylesheets, so we check both inline + the document's collected styles.
+    // Each provider card is a <label> wrapping a visually-hidden native radio; the
+    // aria-hidden icon span lives inside it.
+    const iconSpans = Array.from(container.querySelectorAll('label span[aria-hidden]'));
     expect(iconSpans).toHaveLength(4);
 
     const collectedStyles = [
@@ -243,6 +245,8 @@ describe('SelectProviderStep', () => {
       await userEvent.click(screen.getByRole('button', { name: /Continue/i }));
 
       expect(await screen.findByRole('heading', { name: /change provider to google workspace/i })).toBeInTheDocument();
+      // The dialog is named by its heading so assistive tech announces it.
+      expect(screen.getByRole('dialog', { name: /change provider to google workspace/i })).toBeInTheDocument();
       // Nothing is mutated until the user confirms.
       expect(changeProvider).not.toHaveBeenCalled();
       expect(goNext).not.toHaveBeenCalled();
@@ -268,6 +272,54 @@ describe('SelectProviderStep', () => {
       });
     });
 
+    it('keeps the dialog open and surfaces the error inline when the change fails', async () => {
+      resetMocks();
+      contextState.provider = 'saml_okta';
+      contextState.hasConnection = true;
+      changeProvider.mockRejectedValue(
+        new ClerkRuntimeError('failed to change provider', {
+          code: 'enterprise_connection_creation_failed',
+        }),
+      );
+      const { wrapper } = await createFixtures();
+      const { userEvent } = renderStep(wrapper);
+
+      await userEvent.click(screen.getByRole('radio', { name: 'Google Workspace' }));
+      await userEvent.click(screen.getByRole('button', { name: /Continue/i }));
+
+      await userEvent.click(await screen.findByRole('button', { name: 'Change provider' }));
+
+      await waitFor(() => {
+        expect(changeProvider).toHaveBeenCalledWith('saml_google');
+      });
+
+      // The error renders inside the still-open dialog and the user never advances.
+      expect(await screen.findByText(/failed to change provider/i)).toBeInTheDocument();
+      expect(screen.getByRole('heading', { name: /change provider to google workspace/i })).toBeInTheDocument();
+      expect(goNext).not.toHaveBeenCalled();
+    });
+
+    it('closes the dialog on Escape without changing the provider', async () => {
+      resetMocks();
+      contextState.provider = 'saml_okta';
+      contextState.hasConnection = true;
+      const { wrapper } = await createFixtures();
+      const { userEvent } = renderStep(wrapper);
+
+      await userEvent.click(screen.getByRole('radio', { name: 'Google Workspace' }));
+      await userEvent.click(screen.getByRole('button', { name: /Continue/i }));
+
+      expect(await screen.findByRole('heading', { name: /change provider to google workspace/i })).toBeInTheDocument();
+
+      await userEvent.keyboard('{Escape}');
+
+      await waitFor(() => {
+        expect(screen.queryByRole('heading', { name: /change provider to/i })).not.toBeInTheDocument();
+      });
+      expect(changeProvider).not.toHaveBeenCalled();
+      expect(goNext).not.toHaveBeenCalled();
+    });
+
     it('keeps the connection and stays put when the dialog is cancelled', async () => {
       resetMocks();
       contextState.provider = 'saml_okta';

From 8d747be82d15f67b8495539979275ee390705f38 Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 16:55:24 -0300
Subject: [PATCH 4/8] fix(ui): mark wizard steps complete by guard, not
 position

The SSO wizard stepper derived each step's completed tick positionally
(sits before the current step), so navigating back un-ticked steps whose
work was actually done. Re-entering an already-active connection showed
later steps as incomplete depending on where the user stood.

Add an optional per-step `isComplete` predicate to the wizard step config,
resolved into the stepper's `isCompleted` flag, with the positional value
kept as the fallback so wizards that declare no predicate are unchanged.
The labeled outer steps now report completion from the same connection
flags their guards use, so an active connection shows every step ticked
regardless of the current position.
---
 .../ConfigureSSO/ConfigureSSOWizard.tsx       | 29 ++++++++--
 .../ConfigureSSO.navigation.test.tsx          | 53 +++++++++++++++++++
 .../__tests__/useWizardMachine.test.tsx       | 19 +++++++
 .../ConfigureSSO/elements/Wizard/types.ts     | 15 +++++-
 .../elements/Wizard/useWizardMachine.ts       | 10 ++--
 5 files changed, 117 insertions(+), 9 deletions(-)

diff --git a/packages/ui/src/components/ConfigureSSO/ConfigureSSOWizard.tsx b/packages/ui/src/components/ConfigureSSO/ConfigureSSOWizard.tsx
index 1dac0d90d4b..975723d4a53 100644
--- a/packages/ui/src/components/ConfigureSSO/ConfigureSSOWizard.tsx
+++ b/packages/ui/src/components/ConfigureSSO/ConfigureSSOWizard.tsx
@@ -20,13 +20,34 @@ export const ConfigureSSOWizard = ({ title, forceInitialStep, ...props }: Config
 
   const steps = React.useMemo<WizardStepConfig[]>(
     () => [
-      { id: 'verify-domain', label: 'Domains' },
+      // `isComplete` is position-independent (unlike the stepper's positional
+      // default), so re-entering an active connection ticks every step wherever the
+      // user stands. Each mirrors its guard except `activate`, whose completion is
+      // its own terminal `isActive`; `configure` keys off real configuration (or
+      // active), NOT a bare `hasConnection`, so a just-created-but-unconfigured
+      // connection does not read as done.
+      { id: 'verify-domain', label: 'Domains', isComplete: () => allDomainsVerified },
       // `select-provider` now lives inside `configure` as its first sub-step, so
       // reaching `configure` only requires verified domains (fresh start) or an
       // existing connection (resume / change-provider).
-      { id: 'configure', label: 'Connection', guard: () => allDomainsVerified || c.hasConnection },
-      { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
-      { id: 'activate', label: 'Activate', guard: () => c.hasSuccessfulTestRun || c.isActive },
+      {
+        id: 'configure',
+        label: 'Connection',
+        guard: () => allDomainsVerified || c.hasConnection,
+        isComplete: () => c.hasMinimumConfiguration || c.isActive,
+      },
+      {
+        id: 'test',
+        label: 'Test',
+        guard: () => c.hasMinimumConfiguration || c.isActive,
+        isComplete: () => c.hasSuccessfulTestRun || c.isActive,
+      },
+      {
+        id: 'activate',
+        label: 'Activate',
+        guard: () => c.hasSuccessfulTestRun || c.isActive,
+        isComplete: () => c.isActive,
+      },
     ],
     [c, allDomainsVerified],
   );
diff --git a/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx b/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx
index ce2701cdb7b..172881fbbb1 100644
--- a/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx
+++ b/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx
@@ -267,4 +267,57 @@ describe('ConfigureSSO wizard navigation (integration)', () => {
     expect(getByText('Test')).toBeInTheDocument();
     expect(getByText('Activate')).toBeInTheDocument();
   });
+
+  // Completion is guard-driven, not positional: re-entering an ACTIVE connection
+  // shows every stepper step ticked even after navigating BACK to an earlier step.
+  // A completed (non-current) bullet renders a checkmark instead of its number, so
+  // exactly one bullet — the current one — still shows a digit. Under the old
+  // positional logic the steps AFTER current would lose their tick and show their
+  // numbers again, so this asserts the fix directly.
+  it('re-entering an active connection keeps every step completed after navigating back', async () => {
+    const { wrapper, fixtures } = await createFixtures(withAdminOrgUser);
+
+    fixtures.clerk.organization?.getEnterpriseConnections.mockResolvedValue([
+      { ...configuredConnection, id: 'ent_active', active: true } as any,
+    ]);
+    fixtures.clerk.organization?.getEnterpriseConnectionTestRuns.mockResolvedValue({
+      data: [],
+      total_count: 0,
+    } as any);
+    mockVerifiedDomains(fixtures);
+
+    const { container, findByText, userEvent } = render(<ConfigureSSO />, { wrapper });
+
+    // Mounts on the activate step (active connection short-circuits to it).
+    await findByText(/sso connection is active/i);
+
+    const stepper = () => container.querySelector('.cl-configureSSOStepper') as HTMLElement;
+    const bulletDigitCount = () =>
+      Array.from(stepper().querySelectorAll('.cl-configureSSOStepperItemBullet')).filter(el =>
+        /\d/.test(el.textContent ?? ''),
+      ).length;
+    const stepperLabels = () =>
+      Array.from(stepper().querySelectorAll('.cl-configureSSOStepperItemLabel')).map(el => el.textContent);
+    const stepperButton = (label: string) =>
+      Array.from(stepper().querySelectorAll<HTMLButtonElement>('.cl-configureSSOStepperItem')).find(
+        btn => btn.textContent?.trim() === label,
+      )!;
+
+    // The breadcrumb carries all four labels.
+    expect(stepperLabels()).toEqual(['Domains', 'Connection', 'Test', 'Activate']);
+
+    // On the terminal step, the first three bullets are already ticked (checkmarks)
+    // and only the current 'Activate' bullet shows its number.
+    expect(bulletDigitCount()).toBe(1);
+
+    // Navigate BACK to the first step via the breadcrumb. Every step's guard still
+    // holds for an active connection, so 'Domains' is reachable.
+    await userEvent.click(stepperButton('Domains'));
+
+    // Positional completion would now un-tick Connection/Test/Activate (they sit
+    // AFTER current) and show their numbers. Guard-driven completion keeps them
+    // ticked, so still only the current 'Domains' bullet shows a digit.
+    expect(bulletDigitCount()).toBe(1);
+    expect(stepperLabels()).toEqual(['Domains', 'Connection', 'Test', 'Activate']);
+  });
 });
diff --git a/packages/ui/src/components/ConfigureSSO/elements/Wizard/__tests__/useWizardMachine.test.tsx b/packages/ui/src/components/ConfigureSSO/elements/Wizard/__tests__/useWizardMachine.test.tsx
index 9daaeb98c98..731686fa79c 100644
--- a/packages/ui/src/components/ConfigureSSO/elements/Wizard/__tests__/useWizardMachine.test.tsx
+++ b/packages/ui/src/components/ConfigureSSO/elements/Wizard/__tests__/useWizardMachine.test.tsx
@@ -202,6 +202,25 @@ describe('useWizardMachine — first/last and reachability derivations', () => {
     expect(byId.a).toBe(true);
     expect(byId.b).toBe(false);
   });
+
+  it('isComplete predicate overrides the positional default (position-independent completion)', () => {
+    // 'a' declares its work UNdone and 'c' declares it DONE — independent of where
+    // current sits. Seed on 'b' (the middle): positionally 'a' would read complete
+    // and 'c' incomplete, but the predicates flip both, proving `isComplete` wins.
+    const { result } = renderMachine({
+      config: cfg([
+        { id: 'a', isComplete: () => false },
+        { id: 'b', guard: () => true },
+        { id: 'c', guard: () => true, isComplete: () => true },
+      ]),
+      initialStepId: 'b',
+    });
+    expect(result.current.current).toBe('b');
+    const byId = Object.fromEntries(result.current.activeSteps.map(s => [s.id, s.isCompleted]));
+    expect(byId.a).toBe(false); // predicate overrides "before current" → not complete
+    expect(byId.b).toBe(false); // no predicate, positional: not before itself
+    expect(byId.c).toBe(true); // predicate overrides "after current" → complete
+  });
 });
 
 describe('useWizardMachine — deferred goNext (submit-then-advance race)', () => {
diff --git a/packages/ui/src/components/ConfigureSSO/elements/Wizard/types.ts b/packages/ui/src/components/ConfigureSSO/elements/Wizard/types.ts
index 24b148bfaa9..525837bdde3 100644
--- a/packages/ui/src/components/ConfigureSSO/elements/Wizard/types.ts
+++ b/packages/ui/src/components/ConfigureSSO/elements/Wizard/types.ts
@@ -25,6 +25,15 @@ export interface WizardStepConfig {
    * always-reachable predecessor both rely on that.
    */
   guard?: () => boolean;
+  /**
+   * Inline completion predicate: "is THIS step's work done right now?", decoupled
+   * from the current position. Drives the stepper's completed tick so a step reads
+   * as done whenever its own work is, regardless of where the user currently
+   * stands (re-entering an already-finished flow shows every step ticked).
+   * OMITTED ⇒ fall back to the POSITIONAL default (sits before current) — nested /
+   * per-provider wizards that declare no `isComplete` are unchanged.
+   */
+  isComplete?: () => boolean;
 }
 
 /**
@@ -44,8 +53,10 @@ export interface WizardActiveStep {
   id: string;
   label?: LocalizationKey | string;
   /**
-   * POSITIONAL: the step sits before the current step in declaration order.
-   * Drives the visual "completed" tick only — it is not guard-derived.
+   * Whether this step's work is done — drives the visual "completed" tick. Resolved
+   * from the step's own `isComplete` predicate when it declares one (position-
+   * independent: a finished step stays ticked even when the user navigates back),
+   * otherwise the POSITIONAL default (sits before current in declaration order).
    */
   isCompleted: boolean;
   /**
diff --git a/packages/ui/src/components/ConfigureSSO/elements/Wizard/useWizardMachine.ts b/packages/ui/src/components/ConfigureSSO/elements/Wizard/useWizardMachine.ts
index 2faddce388a..6f0264f6f66 100644
--- a/packages/ui/src/components/ConfigureSSO/elements/Wizard/useWizardMachine.ts
+++ b/packages/ui/src/components/ConfigureSSO/elements/Wizard/useWizardMachine.ts
@@ -213,8 +213,10 @@ export const useWizardMachine = ({ config, parentWizard, initialStepId }: UseWiz
   // Breadcrumb-facing active steps: every descriptor, in declaration order.
   // Derived synchronously from the live descriptors — known before `current` is
   // resolved, so there is no inconsistency window. Each item carries
-  // `isCompleted` (POSITIONAL: sits before current in declaration order) and
-  // `isReachable` (GUARD-DRIVEN: its entry guard holds now — the single source
+  // `isCompleted` (the step's own `isComplete` predicate when it declares one —
+  // position-INDEPENDENT, so a finished step stays ticked after a back-nav —
+  // otherwise the POSITIONAL fallback: sits before current in declaration order)
+  // and `isReachable` (GUARD-DRIVEN: its entry guard holds now — the single source
   // the stepper binds `isDisabled = !isReachable` to and the same predicate
   // `goToStep` checks). Whether an item appears in the breadcrumb is the header's
   // call (it filters on `label`), not the machine's.
@@ -224,7 +226,9 @@ export const useWizardMachine = ({ config, parentWizard, initialStepId }: UseWiz
     return descriptors.map((s, descriptorIndex) => ({
       id: s.id,
       label: s.label,
-      isCompleted: currentDescriptorIndex >= 0 && descriptorIndex < currentDescriptorIndex,
+      isCompleted: s.isComplete
+        ? s.isComplete()
+        : currentDescriptorIndex >= 0 && descriptorIndex < currentDescriptorIndex,
       isReachable: guardHolds(s),
     }));
   }, [config, current]);

From c27f65fd919e216f5449a2ff7bf2b2f0c8c7073b Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 16:55:31 -0300
Subject: [PATCH 5/8] fix(ui): show overview-shaped loading state on the
 organization security page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The security page rendered a wizard-shaped skeleton (stepper + centered
spinner + disabled footer) while loading, even though the default view is
the overview card. On load this flashed a wizard layout that then popped
into a different overview card, and the page "Security" header was missing
during load.

While loading in the overview view, keep the page chrome stable — the
ProfileCard.Page and the "Security" header — and render an overview-shaped
placeholder for the SSO section (the section frame with an in-frame
spinner) so the settled overview replaces it in place. The wizard skeleton
now only renders when loading happens within the wizard view.
---
 .../OrganizationSecurityPage.tsx              | 112 +++++++++++++-----
 .../OrganizationSecurityPage.test.tsx         |  30 ++++-
 2 files changed, 110 insertions(+), 32 deletions(-)

diff --git a/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx b/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx
index 09e3953fd57..900d1eaab4b 100644
--- a/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx
+++ b/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx
@@ -3,8 +3,9 @@ import React, { useState } from 'react';
 
 import { Header } from '@/ui/elements/Header';
 import { ProfileCard } from '@/ui/elements/ProfileCard';
+import { ProfileSection } from '@/ui/elements/Section';
 
-import { Col, descriptors, Icon, localizationKeys, SimpleButton, Text } from '../../customizables';
+import { Col, descriptors, Flex, Icon, localizationKeys, SimpleButton, Spinner, Text } from '../../customizables';
 import { ChevronLeft } from '../../icons';
 import { ConfigureSSOProtect } from '../ConfigureSSO/ConfigureSSO';
 import { ConfigureSSOSkeleton } from '../ConfigureSSO/ConfigureSSOSkeleton';
@@ -49,8 +50,22 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
     setView('wizard');
   };
 
+  // Loading is on mount, where `view` is still 'overview': keep the page chrome
+  // (the "Security" header + the SSO section frame) stable and swap only the
+  // section body for a placeholder, so the settled overview replaces it in place
+  // — no header pop-in, no swap into a differently-shaped wizard skeleton. The
+  // wizard skeleton stays for the rare case loading is ever entered from within
+  // the wizard view itself.
   if (isLoading) {
-    return <ConfigureSSOSkeleton />;
+    return view === 'wizard' ? (
+      <ConfigureSSOSkeleton />
+    ) : (
+      <ConfigureSSOProtect>
+        <SecurityPageOverview>
+          <SecuritySsoSectionSkeleton />
+        </SecurityPageOverview>
+      </ConfigureSSOProtect>
+    );
   }
 
   const backControl = (
@@ -77,34 +92,17 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
   return (
     <ConfigureSSOProtect>
       {view === 'overview' ? (
-        <ProfileCard.Page>
-          <Col
-            elementDescriptor={descriptors.page}
-            sx={t => ({ gap: t.space.$8 })}
-          >
-            <Col
-              elementDescriptor={descriptors.profilePage}
-              elementId={descriptors.profilePage.setId('organizationSecurity')}
-            >
-              <Header.Root>
-                <Header.Title
-                  localizationKey={localizationKeys('organizationProfile.securityPage.title')}
-                  sx={t => ({ marginBottom: t.space.$4 })}
-                  textVariant='h2'
-                />
-              </Header.Root>
-              <SecuritySsoSection
-                connection={organizationEnterpriseConnection}
-                enterpriseConnection={enterpriseConnection}
-                setConnectionActive={enterpriseConnectionMutations.setConnectionActive}
-                deleteConnection={enterpriseConnectionMutations.deleteConnection}
-                organizationName={organization?.name ?? ''}
-                contentRef={contentRef}
-                onConfigure={openWizard}
-              />
-            </Col>
-          </Col>
-        </ProfileCard.Page>
+        <SecurityPageOverview>
+          <SecuritySsoSection
+            connection={organizationEnterpriseConnection}
+            enterpriseConnection={enterpriseConnection}
+            setConnectionActive={enterpriseConnectionMutations.setConnectionActive}
+            deleteConnection={enterpriseConnectionMutations.deleteConnection}
+            organizationName={organization?.name ?? ''}
+            contentRef={contentRef}
+            onConfigure={openWizard}
+          />
+        </SecurityPageOverview>
       ) : (
         <ConfigureSSOWizard
           organizationEnterpriseConnection={organizationEnterpriseConnection}
@@ -122,3 +120,57 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
     </ConfigureSSOProtect>
   );
 };
+
+/**
+ * The overview's stable page chrome — the security `ProfileCard.Page` and its
+ * "Security" header. Both the settled overview and the on-mount loading state
+ * render through this, so the section body is the only thing that swaps in.
+ */
+const SecurityPageOverview = ({ children }: { children: React.ReactNode }): JSX.Element => (
+  <ProfileCard.Page>
+    <Col
+      elementDescriptor={descriptors.page}
+      sx={t => ({ gap: t.space.$8 })}
+    >
+      <Col
+        elementDescriptor={descriptors.profilePage}
+        elementId={descriptors.profilePage.setId('organizationSecurity')}
+      >
+        <Header.Root>
+          <Header.Title
+            localizationKey={localizationKeys('organizationProfile.securityPage.title')}
+            sx={t => ({ marginBottom: t.space.$4 })}
+            textVariant='h2'
+          />
+        </Header.Root>
+        {children}
+      </Col>
+    </Col>
+  </ProfileCard.Page>
+);
+
+/**
+ * Overview-shaped loading placeholder for the SSO section: the real section's
+ * frame (same title + id) wrapping a centered spinner. Mirrors how other
+ * OrganizationProfile sections show in-frame loading rather than swapping in a
+ * differently-shaped skeleton.
+ */
+const SecuritySsoSectionSkeleton = (): JSX.Element => (
+  <ProfileSection.Root
+    title={localizationKeys('organizationProfile.securityPage.ssoSection.title')}
+    id='sso'
+    centered={false}
+  >
+    <Flex
+      align='center'
+      justify='center'
+      sx={t => ({ paddingBlock: t.space.$5 })}
+    >
+      <Spinner
+        size='sm'
+        colorScheme='neutral'
+        elementDescriptor={descriptors.spinner}
+      />
+    </Flex>
+  </ProfileSection.Root>
+);
diff --git a/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx b/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx
index adb2789c011..6549d14e374 100644
--- a/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx
+++ b/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx
@@ -61,9 +61,11 @@ describe('OrganizationSecurityPage', () => {
 
       renderPage(wrapper);
 
-      expect(await screen.findByRole('heading', { name: 'Security' })).toBeInTheDocument();
+      // The "Security" header now also renders during the loading placeholder, so
+      // wait on the settled badge before asserting the page chrome and content.
+      expect(await screen.findByText('Unconfigured')).toBeInTheDocument();
+      expect(screen.getByRole('heading', { name: 'Security' })).toBeInTheDocument();
       expect(screen.getByText('SSO')).toBeInTheDocument();
-      expect(screen.getByText('Unconfigured')).toBeInTheDocument();
       expect(screen.getByText(DESCRIPTION_LINE_1)).toBeInTheDocument();
       expect(screen.getByText(DESCRIPTION_LINE_2)).toBeInTheDocument();
       expect(screen.getByRole('button', { name: 'Start configuration' })).toBeInTheDocument();
@@ -186,6 +188,30 @@ describe('OrganizationSecurityPage', () => {
     });
   });
 
+  describe('loading state', () => {
+    it('renders the overview chrome (the Security header, no wizard stepper) while loading', async () => {
+      const { wrapper, fixtures } = await createFixtures(withSecurityPageFixtures);
+
+      // Hold the source query pending so the page stays in its on-mount loading
+      // state (view is still 'overview').
+      fixtures.clerk.organization?.getEnterpriseConnections.mockReturnValue(new Promise(() => {}) as any);
+      fixtures.clerk.organization?.getEnterpriseConnectionTestRuns.mockResolvedValue({
+        data: [],
+        total_count: 0,
+      } as any);
+
+      const { container } = renderPage(wrapper);
+
+      // The page header stays mounted during load — no pop-in when data settles.
+      expect(await screen.findByRole('heading', { name: 'Security' })).toBeInTheDocument();
+      // The SSO section frame is present (overview-shaped), with an in-frame spinner.
+      expect(container.querySelector('.cl-profileSection__sso')).toBeInTheDocument();
+      expect(container.querySelector('.cl-spinner')).toBeInTheDocument();
+      // It is NOT the wizard-shaped skeleton: no stepper renders in the overview load.
+      expect(container.querySelector('.cl-configureSSOStepper')).not.toBeInTheDocument();
+    });
+  });
+
   describe('view switching', () => {
     it('opens the wizard at the first step when Start configuration is clicked', async () => {
       const { wrapper, fixtures } = await createFixtures(withSecurityPageFixtures);

From 44c36f92ebd74808fd6e58fd8191ff6758bb201e Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 17:33:01 -0300
Subject: [PATCH 6/8] fix(ui): simplify organization security page loading to a
 centered spinner

Replace the SSO section-framed loading placeholder with a bare spinner
centered in the remaining content height beneath the Security header,
matching the design. Adds an opt-in sx hook to ProfileCardPage so the
overview can fill the scroll box height during load.
---
 .../OrganizationSecurityPage.tsx              | 67 ++++++++-----------
 .../OrganizationSecurityPage.test.tsx         | 14 ++--
 .../elements/ProfileCard/ProfileCardPage.tsx  | 45 ++++++++-----
 3 files changed, 65 insertions(+), 61 deletions(-)

diff --git a/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx b/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx
index 900d1eaab4b..f47282af070 100644
--- a/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx
+++ b/packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx
@@ -3,7 +3,6 @@ import React, { useState } from 'react';
 
 import { Header } from '@/ui/elements/Header';
 import { ProfileCard } from '@/ui/elements/ProfileCard';
-import { ProfileSection } from '@/ui/elements/Section';
 
 import { Col, descriptors, Flex, Icon, localizationKeys, SimpleButton, Spinner, Text } from '../../customizables';
 import { ChevronLeft } from '../../icons';
@@ -50,19 +49,27 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
     setView('wizard');
   };
 
-  // Loading is on mount, where `view` is still 'overview': keep the page chrome
-  // (the "Security" header + the SSO section frame) stable and swap only the
-  // section body for a placeholder, so the settled overview replaces it in place
-  // — no header pop-in, no swap into a differently-shaped wizard skeleton. The
-  // wizard skeleton stays for the rare case loading is ever entered from within
-  // the wizard view itself.
+  // Loading is on mount, where `view` is still 'overview': keep the "Security"
+  // header stable so the settled overview replaces the body in place (no header
+  // pop-in) and center a spinner in the remaining height beneath it. The wizard
+  // skeleton stays for the rare case loading is ever entered from the wizard view.
   if (isLoading) {
     return view === 'wizard' ? (
       <ConfigureSSOSkeleton />
     ) : (
       <ConfigureSSOProtect>
-        <SecurityPageOverview>
-          <SecuritySsoSectionSkeleton />
+        <SecurityPageOverview fillHeight>
+          <Flex
+            align='center'
+            justify='center'
+            sx={t => ({ flex: 1, paddingBlock: t.space.$5 })}
+          >
+            <Spinner
+              size='xs'
+              colorScheme='neutral'
+              elementDescriptor={descriptors.spinner}
+            />
+          </Flex>
         </SecurityPageOverview>
       </ConfigureSSOProtect>
     );
@@ -125,16 +132,26 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
  * The overview's stable page chrome — the security `ProfileCard.Page` and its
  * "Security" header. Both the settled overview and the on-mount loading state
  * render through this, so the section body is the only thing that swaps in.
+ *
+ * `fillHeight` grows the page to the scroll box so the loading state's spinner
+ * can center in the remaining height beneath the header.
  */
-const SecurityPageOverview = ({ children }: { children: React.ReactNode }): JSX.Element => (
-  <ProfileCard.Page>
+const SecurityPageOverview = ({
+  children,
+  fillHeight = false,
+}: {
+  children: React.ReactNode;
+  fillHeight?: boolean;
+}): JSX.Element => (
+  <ProfileCard.Page sx={fillHeight ? { flex: 1 } : undefined}>
     <Col
       elementDescriptor={descriptors.page}
-      sx={t => ({ gap: t.space.$8 })}
+      sx={t => ({ gap: t.space.$8, ...(fillHeight && { flex: 1 }) })}
     >
       <Col
         elementDescriptor={descriptors.profilePage}
         elementId={descriptors.profilePage.setId('organizationSecurity')}
+        sx={fillHeight ? { flex: 1 } : undefined}
       >
         <Header.Root>
           <Header.Title
@@ -148,29 +165,3 @@ const SecurityPageOverview = ({ children }: { children: React.ReactNode }): JSX.
     </Col>
   </ProfileCard.Page>
 );
-
-/**
- * Overview-shaped loading placeholder for the SSO section: the real section's
- * frame (same title + id) wrapping a centered spinner. Mirrors how other
- * OrganizationProfile sections show in-frame loading rather than swapping in a
- * differently-shaped skeleton.
- */
-const SecuritySsoSectionSkeleton = (): JSX.Element => (
-  <ProfileSection.Root
-    title={localizationKeys('organizationProfile.securityPage.ssoSection.title')}
-    id='sso'
-    centered={false}
-  >
-    <Flex
-      align='center'
-      justify='center'
-      sx={t => ({ paddingBlock: t.space.$5 })}
-    >
-      <Spinner
-        size='sm'
-        colorScheme='neutral'
-        elementDescriptor={descriptors.spinner}
-      />
-    </Flex>
-  </ProfileSection.Root>
-);
diff --git a/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx b/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx
index 6549d14e374..9e4a615d4cf 100644
--- a/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx
+++ b/packages/ui/src/components/OrganizationProfile/__tests__/OrganizationSecurityPage.test.tsx
@@ -189,7 +189,7 @@ describe('OrganizationSecurityPage', () => {
   });
 
   describe('loading state', () => {
-    it('renders the overview chrome (the Security header, no wizard stepper) while loading', async () => {
+    it('renders the Security header and a centered spinner (no section frame, no wizard stepper) while loading', async () => {
       const { wrapper, fixtures } = await createFixtures(withSecurityPageFixtures);
 
       // Hold the source query pending so the page stays in its on-mount loading
@@ -204,10 +204,14 @@ describe('OrganizationSecurityPage', () => {
 
       // The page header stays mounted during load — no pop-in when data settles.
       expect(await screen.findByRole('heading', { name: 'Security' })).toBeInTheDocument();
-      // The SSO section frame is present (overview-shaped), with an in-frame spinner.
-      expect(container.querySelector('.cl-profileSection__sso')).toBeInTheDocument();
-      expect(container.querySelector('.cl-spinner')).toBeInTheDocument();
-      // It is NOT the wizard-shaped skeleton: no stepper renders in the overview load.
+
+      // The loading body is a bare spinner centered in the remaining content area.
+      const spinner = container.querySelector('.cl-spinner');
+      expect(spinner).toBeInTheDocument();
+      expect(spinner?.parentElement).toHaveStyle({ alignItems: 'center', justifyContent: 'center' });
+
+      // No overview section frame and no wizard-shaped skeleton during load.
+      expect(container.querySelector('.cl-profileSection__sso')).not.toBeInTheDocument();
       expect(container.querySelector('.cl-configureSSOStepper')).not.toBeInTheDocument();
     });
   });
diff --git a/packages/ui/src/elements/ProfileCard/ProfileCardPage.tsx b/packages/ui/src/elements/ProfileCard/ProfileCardPage.tsx
index ecc0d016a49..0e821859137 100644
--- a/packages/ui/src/elements/ProfileCard/ProfileCardPage.tsx
+++ b/packages/ui/src/elements/ProfileCard/ProfileCardPage.tsx
@@ -1,6 +1,7 @@
 import type { PropsWithChildren } from 'react';
 
 import { Col } from '../../customizables';
+import type { ThemableCssProp } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 
 type ProfileCardPageProps = PropsWithChildren<{
@@ -15,6 +16,11 @@ type ProfileCardPageProps = PropsWithChildren<{
    * @default false
    */
   bleeding?: boolean;
+  /**
+   * Extra styles for the page wrapper — e.g. `flex: 1` to fill the scroll box height.
+   * Ignored when neither `padding` nor `bleeding` apply (no wrapper renders).
+   */
+  sx?: ThemableCssProp;
 }>;
 
 /**
@@ -23,31 +29,34 @@ type ProfileCardPageProps = PropsWithChildren<{
  * Each routed page inside `UserProfile` / `OrganizationProfile` should wrap its content
  * in this component
  */
-export const ProfileCardPage = ({ children, padding = true, bleeding = false }: ProfileCardPageProps) => {
+export const ProfileCardPage = ({ children, padding = true, bleeding = false, sx }: ProfileCardPageProps) => {
   if (!padding && !bleeding) {
     return <>{children}</>;
   }
 
   return (
     <Col
-      sx={theme => ({
-        ...(padding && {
-          paddingTop: theme.space.$7,
-          paddingBottom: theme.space.$7,
-          paddingInlineStart: theme.space.$8,
-          paddingInlineEnd: theme.space.$6, //smaller because of stable scrollbar gutter on the parent
-          [mqu.sm]: {
-            padding: `${theme.space.$8} ${theme.space.$5}`,
-          },
-        }),
-        ...(bleeding && {
-          marginInlineStart: `calc(${theme.space.$8} * -1)`,
-          marginInlineEnd: `calc(${theme.space.$6} * -1)`,
-          [mqu.sm]: {
-            marginInline: `calc(${theme.space.$5} * -1)`,
-          },
+      sx={[
+        theme => ({
+          ...(padding && {
+            paddingTop: theme.space.$7,
+            paddingBottom: theme.space.$7,
+            paddingInlineStart: theme.space.$8,
+            paddingInlineEnd: theme.space.$6, //smaller because of stable scrollbar gutter on the parent
+            [mqu.sm]: {
+              padding: `${theme.space.$8} ${theme.space.$5}`,
+            },
+          }),
+          ...(bleeding && {
+            marginInlineStart: `calc(${theme.space.$8} * -1)`,
+            marginInlineEnd: `calc(${theme.space.$6} * -1)`,
+            [mqu.sm]: {
+              marginInline: `calc(${theme.space.$5} * -1)`,
+            },
+          }),
         }),
-      })}
+        sx,
+      ]}
     >
       {children}
     </Col>

From ec943cf0a4c456892efa6f69fb30111026d55973 Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 17:36:57 -0300
Subject: [PATCH 7/8] fix(ui): show the completion check on the current wizard
 step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Render the Checkmark icon whenever isCompleted, removing the previous
!isCurrent guard. A step that is both current and completed now shows
the checkmark (on the dark "you are here" background) instead of
falling through to its number.

Background color precedence is unchanged: isCurrent takes priority over
isCompleted, so the bullet stays the dark $colorForeground circle —
only the icon inside changes from number to checkmark.

Update the navigation test: for a fully active connection all four
steps are completed, so all four bullets render checkmarks and zero
show a digit (including the current step).
---
 .../ConfigureSSO.navigation.test.tsx          | 19 ++++++++++---------
 .../ConfigureSSO/elements/Stepper/Stepper.tsx |  6 +++---
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx b/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx
index 172881fbbb1..3c915acb42c 100644
--- a/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx
+++ b/packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx
@@ -270,10 +270,10 @@ describe('ConfigureSSO wizard navigation (integration)', () => {
 
   // Completion is guard-driven, not positional: re-entering an ACTIVE connection
   // shows every stepper step ticked even after navigating BACK to an earlier step.
-  // A completed (non-current) bullet renders a checkmark instead of its number, so
-  // exactly one bullet — the current one — still shows a digit. Under the old
-  // positional logic the steps AFTER current would lose their tick and show their
-  // numbers again, so this asserts the fix directly.
+  // A completed bullet renders a checkmark regardless of whether it is also the
+  // current step — so for a fully active connection all four bullets show checkmarks
+  // and zero show a digit. Under the old positional logic the steps AFTER current
+  // would lose their tick and show their numbers again, so this asserts the fix directly.
   it('re-entering an active connection keeps every step completed after navigating back', async () => {
     const { wrapper, fixtures } = await createFixtures(withAdminOrgUser);
 
@@ -306,9 +306,9 @@ describe('ConfigureSSO wizard navigation (integration)', () => {
     // The breadcrumb carries all four labels.
     expect(stepperLabels()).toEqual(['Domains', 'Connection', 'Test', 'Activate']);
 
-    // On the terminal step, the first three bullets are already ticked (checkmarks)
-    // and only the current 'Activate' bullet shows its number.
-    expect(bulletDigitCount()).toBe(1);
+    // On the terminal step all four steps are complete, so all four bullets show
+    // checkmarks — including the current 'Activate' step — and zero show a digit.
+    expect(bulletDigitCount()).toBe(0);
 
     // Navigate BACK to the first step via the breadcrumb. Every step's guard still
     // holds for an active connection, so 'Domains' is reachable.
@@ -316,8 +316,9 @@ describe('ConfigureSSO wizard navigation (integration)', () => {
 
     // Positional completion would now un-tick Connection/Test/Activate (they sit
     // AFTER current) and show their numbers. Guard-driven completion keeps them
-    // ticked, so still only the current 'Domains' bullet shows a digit.
-    expect(bulletDigitCount()).toBe(1);
+    // ticked. 'Domains' is also completed, so its bullet shows a checkmark too —
+    // zero bullets show a digit.
+    expect(bulletDigitCount()).toBe(0);
     expect(stepperLabels()).toEqual(['Domains', 'Connection', 'Test', 'Activate']);
   });
 });
diff --git a/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx b/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx
index c348eb9211b..a99d064ea76 100644
--- a/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx
+++ b/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx
@@ -1,7 +1,7 @@
 import React from 'react';
 
-import { Box, descriptors, Flex, Icon, SimpleButton, Text, Span } from '@/customizables';
-import { ChevronRight, Checkmark } from '@/icons';
+import { Box, descriptors, Flex, Icon, SimpleButton, Span,Text } from '@/customizables';
+import { Checkmark, ChevronRight } from '@/icons';
 
 import type { StepperItemProps, StepperProps } from './types';
 
@@ -82,7 +82,7 @@ const Item = ({
               : theme.colors.$colorMutedForeground,
         })}
       >
-        {isCompleted && !isCurrent ? (
+        {isCompleted ? (
           <Icon
             icon={Checkmark}
             size='sm'

From 821c1e7861b83c81deea9935561315df2bf63639 Mon Sep 17 00:00:00 2001
From: Iago Dahlem Lorensini <iagodahlemlorensini@gmail.com>
Date: Fri, 19 Jun 2026 17:40:30 -0300
Subject: [PATCH 8/8] fix(ui): keep the completion check visible on the current
 step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a step is both current and completed the bullet background is
\$colorForeground (light/white in dark mode). The checkmark was always
colored \$white, making it invisible. Use \$colorBackground (the inverse)
for the current step — the same token the step number already uses —
so the check stays readable in both themes.
---
 .../ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx b/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx
index a99d064ea76..8fd67cd329a 100644
--- a/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx
+++ b/packages/ui/src/components/ConfigureSSO/elements/Stepper/Stepper.tsx
@@ -86,7 +86,7 @@ const Item = ({
           <Icon
             icon={Checkmark}
             size='sm'
-            sx={theme => ({ color: theme.colors.$white })}
+            sx={theme => ({ color: isCurrent ? theme.colors.$colorBackground : theme.colors.$white })}
           />
         ) : (
           <Text