@djangocfg/layouts 2.1.567 → 2.1.569

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.567",
+  "version": "2.1.569",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -90,11 +90,11 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.567",
-    "@djangocfg/api": "^2.1.567",
-    "@djangocfg/devtools": "^2.1.567",
-    "@djangocfg/i18n": "^2.1.567",
-    "@djangocfg/ui-core": "^2.1.567",
+    "@djangocfg/analytics": "^2.1.569",
+    "@djangocfg/api": "^2.1.569",
+    "@djangocfg/devtools": "^2.1.569",
+    "@djangocfg/i18n": "^2.1.569",
+    "@djangocfg/ui-core": "^2.1.569",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -124,12 +124,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.567",
-    "@djangocfg/api": "^2.1.567",
-    "@djangocfg/devtools": "^2.1.567",
-    "@djangocfg/i18n": "^2.1.567",
-    "@djangocfg/typescript-config": "^2.1.567",
-    "@djangocfg/ui-core": "^2.1.567",
+    "@djangocfg/analytics": "^2.1.569",
+    "@djangocfg/api": "^2.1.569",
+    "@djangocfg/devtools": "^2.1.569",
+    "@djangocfg/i18n": "^2.1.569",
+    "@djangocfg/typescript-config": "^2.1.569",
+    "@djangocfg/ui-core": "^2.1.569",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/layouts/AuthLayout/AuthLayout.tsx

@@ -1,9 +1,11 @@
 /**
  * Auth Layout
  *
- * Shell-based authentication layout with two variants:
- * - `centered` (default) — Apple-style frameless, centered, glow background
- * - `split` — Two-column on desktop (form + sidebar), single-column on mobile
+ * Shell-based authentication layout with three variants:
+ * - `fullsplit` (default) — full-bleed 50/50: photo half carrying the brand,
+ *   form on a solid panel opposite. Collapses to a plain centered form on mobile
+ * - `centered` — Apple-style frameless, centered, glow background
+ * - `split` — Two-column frosted card on desktop, single-column on mobile
  *
  * Supports: email/phone OTP, OAuth (GitHub), 2FA (TOTP + backup codes)
  */
@@ -17,6 +19,7 @@ import { useAnalytics } from '@djangocfg/analytics';
 import { useAppT } from '@djangocfg/i18n';
 
 import { Suspense } from '../../components';
+import { AuthBrandPanel } from './components/shared';
 import { OAuthCallback } from './components/oauth';
 import { IdentifierStep, OTPStep, TwoFactorStep } from './components/steps';
 import { AUTH } from './constants';
@@ -35,12 +38,34 @@ import type { AuthLayoutProps } from './types';
 interface AuthLayoutContextValue {
   /** True when the consumer passed custom children — step headers should be hidden */
   hideHeader: boolean;
+  /**
+   * True when the brand is already rendered on the media half, so the form
+   * header must not repeat it.
+   *
+   * A statement about the DESKTOP layout only: `fullsplit` drops the media half
+   * below 1024px, where the logo above the form is the only brand left. CSS
+   * owns that half of the decision on the same breakpoint — see
+   * `.auth-header[data-brand-elsewhere]` in `auth.css`.
+   */
+  hasBrandPanel: boolean;
 }
 
-const AuthLayoutContext = createContext<AuthLayoutContextValue>({ hideHeader: false });
+const AuthLayoutContext = createContext<AuthLayoutContextValue>({
+  hideHeader: false,
+  hasBrandPanel: false,
+});
 
 export const useAuthLayoutContext = (): AuthLayoutContextValue => useContext(AuthLayoutContext);
 
+/**
+ * The provider itself, for harnesses that mount the steps without `AuthLayout`
+ * (Storybook does, via `AuthShell`). Without it those previews always read the
+ * context defaults, so a story cannot show what a real screen renders — the
+ * brand appeared both on the photo and above the form, in the one story meant
+ * to prove it does not.
+ */
+export const AuthLayoutProvider = AuthLayoutContext.Provider;
+
 // ─── Layout ──────────────────────────────────────────────────────────────────
 
 export const AuthLayout: React.FC<AuthLayoutProps> = (props) => {
@@ -49,6 +74,7 @@ export const AuthLayout: React.FC<AuthLayoutProps> = (props) => {
     mediaSide = 'left',
     background,
     sidebar,
+    logo,
     enableGithubAuth,
     // No default here — an unset prop falls through to the saved back-url /
     // resolved routes.defaultCallback chain at navigation time (AuthSuccess).
@@ -61,7 +87,28 @@ export const AuthLayout: React.FC<AuthLayoutProps> = (props) => {
 
   const hideHeader = Boolean(children);
 
-  const layoutContextValue = useMemo(() => ({ hideHeader }), [hideHeader]);
+  /*
+   * The media half of `fullsplit` is a full-height photograph, and its content
+   * is the `sidebar` slot. Left to the consumer it was simply empty in four of
+   * the nine apps that mount this layout — a large photo carrying nothing while
+   * the brand crowded the form opposite. So when the app gives us a brand and
+   * no sidebar, the layout puts the brand where the room is.
+   *
+   * An explicit `sidebar` always wins; `centered` and `split` are untouched
+   * (neither has a photo half to fill).
+   */
+  const resolvedSidebar = useMemo(() => {
+    if (sidebar) return sidebar;
+    if (variant !== 'fullsplit' || !logo) return undefined;
+    return <AuthBrandPanel logo={logo} />;
+  }, [sidebar, variant, logo]);
+
+  const hasBrandPanel = !sidebar && Boolean(resolvedSidebar);
+
+  const layoutContextValue = useMemo(
+    () => ({ hideHeader, hasBrandPanel }),
+    [hideHeader, hasBrandPanel],
+  );
 
   const oauthCallback = useMemo(() => {
     if (!enableGithubAuth) return null;
@@ -84,7 +131,7 @@ export const AuthLayout: React.FC<AuthLayoutProps> = (props) => {
           <AuthSuccessOverlay />
           <AuthFunnelTracker />
 
-          <AuthShell variant={variant} mediaSide={mediaSide} background={background} sidebar={sidebar} className={className}>
+          <AuthShell variant={variant} mediaSide={mediaSide} background={background} sidebar={resolvedSidebar} className={className}>
             {/* Handle OAuth callback when GitHub auth is enabled */}
             {oauthCallback}
 
@@ -146,24 +193,22 @@ const AuthContent: React.FC = memo(function AuthContent() {
 });
 
 const AuthSuccessOverlay: React.FC = memo(function AuthSuccessOverlay() {
-  const { step, logo, redirectUrl } = useAuthFormContext();
+  const { step, redirectUrl } = useAuthFormContext();
 
   if (step !== 'success') {
     return null;
   }
 
-  return <AuthSuccess logo={logo} redirectUrl={redirectUrl} />;
+  return <AuthSuccess redirectUrl={redirectUrl} />;
 });
 
 // AuthSuccess component - Apple-style success screen
 interface AuthSuccessInlineProps {
-  logo?: React.ReactNode;
   redirectUrl?: string;
   redirectDelay?: number;
 }
 
 const AuthSuccess: React.FC<AuthSuccessInlineProps> = memo(function AuthSuccess({
-  logo,
   redirectUrl,
   redirectDelay = AUTH.REDIRECT_DELAY,
 }) {
@@ -172,7 +217,13 @@ const AuthSuccess: React.FC<AuthSuccessInlineProps> = memo(function AuthSuccess(
   const t = useAppT();
   const [isVisible, setIsVisible] = React.useState(false);
 
-  const successMessage = React.useMemo(() => t('layouts.auth.success.message'), [t]);
+  const content = React.useMemo(
+    () => ({
+      message: t('layouts.auth.success.message'),
+      redirecting: t('layouts.auth.success.redirecting'),
+    }),
+    [t],
+  );
 
   React.useEffect(() => {
     const animTimer = setTimeout(() => setIsVisible(true), AUTH.ANIMATION_START_DELAY);
@@ -189,21 +240,41 @@ const AuthSuccess: React.FC<AuthSuccessInlineProps> = memo(function AuthSuccess(
     };
   }, [redirectUrl, redirectDelay, router, routes.defaultCallback]);
 
-  return (
-    <div className="auth-success-overlay">
-      <div className="auth-success-content">
-        {logo ? (
-          <span
-            className="auth-success-logo"
-            style={{ opacity: isVisible ? 1 : 0 }}
-          >
-            {logo}
-          </span>
-        ) : (
-          <div
-            className="auth-success-check"
-            style={{ opacity: isVisible ? 1 : 0 }}
-          >
+  return <AuthSuccessScreen visible={isVisible} {...content} />;
+});
+
+export interface AuthSuccessScreenProps {
+  /** Drives the group fade. False on the first frame, then true. */
+  visible?: boolean;
+  /** The outcome. */
+  message: string;
+  /** What the pause before the redirect is for. */
+  redirecting?: string;
+}
+
+/**
+ * The success screen's markup, with no timer and no router.
+ *
+ * Split out so it can be rendered on its own: the screen had no Storybook
+ * story at all, because the only thing that could draw it also navigated away
+ * 1.5s later. A screen nobody can look at is a screen nobody reviews.
+ *
+ * The checkmark is the confirmation, always — the brand is not a substitute
+ * for it. Showing the logo INSTEAD (the previous behaviour, whenever an app
+ * passed `logo`) produced a screen that never actually said the sign-in
+ * worked; it read as a splash screen, which is what a sign-in has just
+ * finished not being.
+ *
+ * `role="status"` rather than `alert`: this is the expected outcome, so it is
+ * announced politely, and the whole overlay is one live region so a screen
+ * reader hears the confirmation and the redirect notice together.
+ */
+export const AuthSuccessScreen: React.FC<AuthSuccessScreenProps> = memo(
+  function AuthSuccessScreen({ visible = true, message, redirecting }) {
+    return (
+      <div className="auth-success-overlay" role="status" aria-live="polite">
+        <div className="auth-success-content" data-visible={visible}>
+          <div className="auth-success-check">
             <svg
               fill="none"
               stroke="currentColor"
@@ -218,14 +289,15 @@ const AuthSuccess: React.FC<AuthSuccessInlineProps> = memo(function AuthSuccess(
               />
             </svg>
           </div>
-        )}
-        <p
-          className="auth-success-text"
-          style={{ opacity: isVisible ? 1 : 0 }}
-        >
-          {successMessage}
-        </p>
+
+          <div className="auth-success-copy">
+            <p className="auth-success-text">{message}</p>
+            {/* Says what the wait is for. Without it the screen states an
+                outcome and then moves on its own, which reads as a glitch. */}
+            {redirecting && <p className="auth-success-hint">{redirecting}</p>}
+          </div>
+        </div>
       </div>
-    </div>
-  );
-});
+    );
+  },
+);

package/src/layouts/AuthLayout/README.md

@@ -12,15 +12,46 @@ Shell-based authentication layout with three visual variants:
   floating over the `background` image; on mobile it collapses to a plain,
   frameless centered form (no image, no glass, no sidebar).
 
-The logo (when `logo` is set) always renders above the form across all
-variants; the `sidebar` slot should carry the quote/illustration, not a second
-brand mark.
+## Where the brand goes
 
-`logo` is a **`ReactNode`** — pass an inline-SVG brand component, an `<img>`,
-whatever. The layout owns the size: the node is dropped into a fixed slot
-(`.auth-logo`, 56px; `.auth-success-logo`, 72px) and stretched to fill it
-(`width/height: 100%`), so a `currentColor` SVG inherits the slot's size and
-the surrounding text color — no per-theme asset swap needed.
+**One brand per screen, placed where there is room for it.** Pass `logo`; the
+layout decides.
+
+| Variant | Desktop | Below 1024px |
+|---|---|---|
+| `fullsplit` | on the photo half (`AuthBrandPanel`) | above the form |
+| `centered`, `split` | above the form | above the form |
+
+On `fullsplit` the media half is a full-height photograph, and its content is
+the `sidebar` slot. When an app passes `logo` and **no** `sidebar`, the layout
+supplies `AuthBrandPanel` itself and the form header stands its logo down — so
+the photo carries the brand and the form carries only the task. An explicit
+`sidebar` always wins and the logo stays above the form.
+
+> This default exists because the slot was previously the consumer's problem
+> alone: four of the nine apps mounting this layout passed `logo` + `background`
+> and no `sidebar`, rendering a large photograph with nothing on it while the
+> brand crowded the form opposite. Every Storybook story supplied a sidebar of
+> its own, so the shipped configuration was the one never reviewed. See
+> `FullSplitNoSidebar` in `AuthFlow.stories.tsx`.
+
+Below 1024px `fullsplit` drops the media half, so the logo above the form is
+the only brand left and it returns. CSS owns that half of the rule
+(`.auth-header[data-brand-elsewhere]`) — a JS width branch would need a
+viewport the server does not have and would flicker on hydration.
+
+`logo` is a **`ReactNode`** — an inline-SVG brand component, an `<img>`, a
+horizontal lock-up. **The slot fits the artwork, not the reverse:** it caps the
+height (44px in the form header, 2.5rem on the brand panel) and lets the width
+follow, so a square mark and a wide lock-up both keep their aspect ratio. Use a
+`currentColor` SVG and it inherits the surrounding text color — no per-theme
+asset swap.
+
+> Until this was fixed the slot was a hard 56×56 square with `width: 100%` on
+> the child, which silently assumed every brand is square. A horizontal lock-up
+> (mark plus two lines of type) was squeezed into the square and rendered as a
+> scramble — visible in carapis, invisible in mls, whose mark happens to be
+> square.
 
 ```tsx
 <AuthLayout logo={<BrandMark className="text-foreground" />} … />
@@ -98,12 +129,12 @@ import { AuthLayout } from '@djangocfg/layouts';
 | `variant` | `'centered' \| 'split' \| 'fullsplit'` | `'fullsplit'` | Shell layout variant |
 | `mediaSide` | `'left' \| 'right'` | `'left'` | Which side the image half sits on (`fullsplit` only) |
 | `background` | `AuthBackgroundConfig` | — | Background image/gradient/overlay/blur |
-| `sidebar` | `ReactNode` | — | Right column content (split variant only) |
+| `sidebar` | `ReactNode` | — | Media/side column content. On `fullsplit`, omitting it with `logo` set yields the default `AuthBrandPanel` |
 | `sourceUrl` | `string` | — | App URL for analytics/tracking |
 | `redirectUrl` | `string` | `/private` | Where to redirect after auth |
 | `enableGithubAuth` | `boolean` | `false` | Show GitHub OAuth button |
 | `enablePhoneAuth` | `boolean` | `false` | Allow phone number input |
-| `logo` | `ReactNode` | — | Logo node shown above the form and on the success screen. Fills its slot (the layout sizes it); use a `currentColor` SVG for theme adaptivity |
+| `logo` | `ReactNode` | — | Brand node. Placed by variant (see [Where the brand goes](#where-the-brand-goes)); the slot caps its height and keeps its aspect ratio |
 | `termsUrl` | `string` | — | Terms link — rendered in the passive consent line (opens in a new tab) |
 | `privacyUrl` | `string` | — | Privacy link — rendered in the passive consent line (opens in a new tab) |
 | `supportUrl` | `string` | — | Support page link |
@@ -139,7 +170,7 @@ The sign-in flow walks these steps:
 | `identifier` | Email or phone input |
 | `otp` | 4-digit email OTP code entry |
 | `2fa` | TOTP or backup code verification (only if the account already has 2FA) |
-| `success` | Full-screen success overlay → redirect |
+| `success` | Full-screen confirmation → redirect (see below) |
 
 `children` (custom header) are only rendered on the `identifier` step — hidden on all others.
 
@@ -147,6 +178,63 @@ The sign-in flow walks these steps:
 > transitions to it. That value backs the standalone setup UI (`SetupStep` /
 > `SetupStepStandalone`) which **ProfileLayout** reuses for configuring 2FA.
 
+## The success screen
+
+A checkmark, the outcome, and what the wait is for:
+
+```text
+        ✓
+  Signed in successfully
+     Taking you in…
+```
+
+The mark is **always** the checkmark, never the brand. Rendering the logo
+instead (the old behaviour when `logo` was set) produced a screen that never
+actually said the sign-in worked — it read as a splash screen, which is what a
+sign-in has just finished not being. The second line names the redirect, so the
+pause before navigation reads as intent rather than a stall.
+
+The overlay is one `role="status"` live region, so a screen reader hears the
+confirmation and the redirect notice together. Timings live in `constants.ts`
+(`REDIRECT_DELAY`, `ANIMATION_START_DELAY`).
+
+The markup is exported separately as **`AuthSuccessScreen`** — no timer, no
+router — so it can be rendered and reviewed on its own:
+
+```tsx
+<AuthSuccessScreen message="Signed in successfully" redirecting="Taking you in…" />
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `message` | `string` | The outcome |
+| `redirecting` | `string?` | What the pause is for; omitted renders nothing |
+| `visible` | `boolean?` | Drives the group fade. Default `true` |
+
+That split exists because the screen previously had **no story at all**: the
+only component that could draw it also navigated away 1.5s later, so nobody
+could sit and look at it — which is how it kept showing the brand instead of a
+confirmation. See `Success` in `AuthFlow.stories.tsx`.
+
+## Errors
+
+The form never shows a raw transport string. `@djangocfg/api`'s
+`resolveAuthError` (`auth/utils/errors.ts`) decides the copy in one place:
+
+1. **Text the server wrote** (`error` / `detail` / `message`) — it knows the
+   specific reason a status code cannot express ("This code has expired").
+2. **Copy chosen from the status code**, translated, via keys that already
+   exist in all 17 locales (`api.errors.*`, `ui.errors.*`).
+3. A generic sentence.
+
+`HTTP <code>:` strings are rejected on the way through: that is `APIError`
+restating its own status line, and under HTTP/2 `statusText` is empty — which
+is how a bare `HTTP 404:` once rendered under a sign-in field. The code still
+reaches the console through `logAuthFailure`, where diagnosis belongs.
+
+The message renders directly beneath the input it concerns, not at the foot of
+the form.
+
 ## Architecture
 
 AuthLayout is built on a **shell pattern** (inspired by PublicLayout's navbar/footer slots):
@@ -162,6 +250,7 @@ AuthLayout/
 │   └── types.ts           — AuthShellVariant, AuthBackgroundConfig
 ├── components/steps/      — Auth step components (IdentifierStep, OTPStep, ...)
 ├── components/shared/     — Reusable UI primitives (AuthButton, AuthConsent, ...)
+│                          incl. AuthBrandPanel — the default `fullsplit` media content
 ├── styles/
 │   ├── auth.css            — Shared form/button/input styles
 │   ├── centered-shell.css  — Centered variant layout

package/src/layouts/AuthLayout/components/shared/AuthBrandPanel.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import React, { memo } from 'react';
+
+export interface AuthBrandPanelProps {
+  /** The brand node the app already passes to `AuthLayout` as `logo`. */
+  logo: React.ReactNode;
+  /** One line under the mark. Omitted by default — the photo carries the mood. */
+  tagline?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * AuthBrandPanel — what the `fullsplit` media half shows when the app gives it
+ * nothing.
+ *
+ * WHY A DEFAULT EXISTS
+ *
+ * `fullsplit` is the default variant and its left half is a full-height photo.
+ * The content over that photo is the `sidebar` slot, which the package left
+ * entirely to the consumer — so an app passing `logo` + `background` and no
+ * `sidebar` rendered a large photograph with nothing on it, while the brand
+ * crowded the form column opposite. Four of the nine call sites were in exactly
+ * that state; Storybook never showed it because the story harness supplied a
+ * sidebar of its own, so the broken configuration had no story.
+ *
+ * The brand belongs here rather than above the form: the photo half is the
+ * half with room, and a sign-in form reads fastest when it carries only the
+ * task. An app that wants something richer (a quote, a testimonial) still
+ * passes its own `sidebar` and this never renders.
+ *
+ * Text is light because it sits on the scrim `fullsplit-shell.css` paints over
+ * the photo, not on a theme surface — so it does not follow `--foreground`.
+ */
+function AuthBrandPanelRaw({ logo, tagline, className = '' }: AuthBrandPanelProps) {
+  return (
+    <div className={`auth-brand-panel ${className}`}>
+      <span className="auth-brand-panel__mark">{logo}</span>
+      {tagline && <p className="auth-brand-panel__tagline">{tagline}</p>}
+    </div>
+  );
+}
+
+export const AuthBrandPanel = memo(AuthBrandPanelRaw);

package/src/layouts/AuthLayout/components/shared/AuthHeader.tsx

@@ -7,6 +7,14 @@ export interface AuthHeaderProps {
   title: string;
   subtitle?: string;
   identifier?: string;
+  /**
+   * The brand is already rendered elsewhere on this screen (the `fullsplit`
+   * media half). The logo stays in the markup and CSS hides it at the width
+   * where that other half is actually visible — see `.auth-header` in
+   * `auth.css`. Rendering it conditionally in JS instead would need a width
+   * the server does not have, and the brand would flicker on hydration.
+   */
+  brandElsewhere?: boolean;
   className?: string;
 }
 
@@ -15,16 +23,19 @@ export interface AuthHeaderProps {
  *
  * `logo` is any React node (inline-SVG brand component, `<img>`, …), rendered
  * inside an `.auth-logo` wrapper so the existing logo sizing/spacing applies.
+ * The slot fits the artwork rather than the reverse: a square mark and a
+ * horizontal lock-up both keep their aspect ratio.
  */
 function AuthHeaderRaw({
   logo,
   title,
   subtitle,
   identifier,
+  brandElsewhere = false,
   className = '',
 }: AuthHeaderProps) {
   return (
-    <div className={`auth-header ${className}`}>
+    <div className={`auth-header ${className}`} data-brand-elsewhere={brandElsewhere}>
       {logo && (
         <span className="auth-logo" aria-hidden="true">
           {logo}

package/src/layouts/AuthLayout/components/shared/index.ts

@@ -1,3 +1,4 @@
+export { AuthBrandPanel } from './AuthBrandPanel';
 export { AuthContainer } from './AuthContainer';
 export { AuthHeader } from './AuthHeader';
 export { AuthFooter } from './AuthFooter';
@@ -9,6 +10,7 @@ export { AuthOTPInput } from './AuthOTPInput';
 export { WebmailIcon } from './WebmailIcon';
 export { AuthConsent } from './AuthConsent';
 
+export type { AuthBrandPanelProps } from './AuthBrandPanel';
 export type { AuthContainerProps } from './AuthContainer';
 export type { AuthHeaderProps } from './AuthHeader';
 export type { AuthFooterProps } from './AuthFooter';

package/src/layouts/AuthLayout/components/steps/IdentifierStep.tsx

@@ -22,8 +22,8 @@ import {
  * IdentifierStep - Apple-style email input step.
  *
  * Clean, minimal design with:
- * - Optional logo (hidden in the split variant — sidebar carries the brand)
- * - Single email input field
+ * - Optional logo, stood down on desktop when the media half carries the brand
+ * - Single email input field, with its error directly beneath it
  * - Passive consent line (continuing = consent; no opt-in checkbox)
  * - OAuth options
  *
@@ -34,7 +34,7 @@ import {
  * fields change.
  */
 function IdentifierStepRaw() {
-  const { hideHeader } = useAuthLayoutContext();
+  const { hideHeader, hasBrandPanel } = useAuthLayoutContext();
 
   const {
     identifier,
@@ -109,7 +109,14 @@ function IdentifierStepRaw() {
 
   return (
     <AuthContainer step="identifier">
-      {!hideHeader && <AuthHeader logo={logo} title={content.title} subtitle={content.subtitle.email} />}
+      {!hideHeader && (
+        <AuthHeader
+          logo={logo}
+          brandElsewhere={hasBrandPanel}
+          title={content.title}
+          subtitle={content.subtitle.email}
+        />
+      )}
 
       <form onSubmit={handleIdentifierSubmit} className="auth-form-group">
         <Input
@@ -128,6 +135,8 @@ function IdentifierStepRaw() {
           className="auth-input"
         />
 
+        <AuthError message={error} />
+
         {/* Both opt-in rows share `auth-optin` — same control, same weight. */}
         {consentEnabled && (
           <label className="auth-optin">
@@ -161,8 +170,6 @@ function IdentifierStepRaw() {
           </label>
         )}
 
-        <AuthError message={error} />
-
         <AuthButton
           loading={isLoading}
           disabled={!identifier || isRateLimited}

package/src/layouts/AuthLayout/index.ts

@@ -3,7 +3,8 @@
  */
 
 // Main layout
-export { AuthLayout, useAuthLayoutContext } from './AuthLayout';
+export { AuthLayout, AuthSuccessScreen, useAuthLayoutContext } from './AuthLayout';
+export type { AuthSuccessScreenProps } from './AuthLayout';
 
 // Context and hooks
 export { AuthFormProvider, useAuthFormContext } from './context';

package/src/layouts/AuthLayout/styles/auth.css

@@ -14,25 +14,35 @@
   --auth-radius: 0.75rem;
   --auth-radius-sm: 0.5rem;
   --auth-radius-xs: 0.375rem;
+  /* The single vertical step of the auth column. */
+  --auth-gap: 1rem;
 }
 
 /* ===== CONTAINER ===== */
 
+/* One gap governs the column. Two competing scales (1.25rem between blocks,
+   0.875rem inside the form) made the stack pulse unevenly — the header sat
+   further from the field than the field sat from the button, so nothing read
+   as grouped. Blocks that want more room ask for it themselves, below. */
 .auth-container {
   width: 100%;
   max-width: 380px;
   display: flex;
   flex-direction: column;
-  gap: 1.25rem;
+  gap: var(--auth-gap);
 }
 
 /* Meta row at the top of the form — currently hosts the locale picker.
-   Right-aligned, tight, not eating much vertical space; feels like a
-   tab/utility chip rather than a floating control. */
+   It is the first thing in the column but the last thing anyone came here to
+   do, so it is pulled out of the reading order by SIZE and alignment. Not by
+   contrast: `--muted-foreground` is the dimmest token that still clears AA,
+   and fading it toward transparent fails the contract gate — which is what
+   happened to the consent line below. */
 .auth-container__meta {
   display: flex;
   justify-content: flex-end;
-  margin-bottom: -0.5rem;
+  /* Lifted clear of the column's own gap — a utility chip, not a first row. */
+  margin-bottom: calc(var(--auth-gap) * -1);
 }
 
 .auth-locale-trigger {
@@ -40,8 +50,10 @@
   padding-inline: 0.5rem;
   font-size: 0.75rem;
   color: var(--muted-foreground);
+  transition: color 0.15s var(--spring-snappy);
 }
-.auth-locale-trigger:hover {
+.auth-locale-trigger:hover,
+.auth-locale-trigger:focus-visible {
   color: var(--foreground);
 }
 
@@ -62,29 +74,45 @@
 
 /* ===== HEADER ===== */
 
+/* The header is the one block that earns extra space: it separates the brand
+   and the question from the controls that answer it. */
 .auth-header {
   text-align: center;
   display: flex;
   flex-direction: column;
   align-items: center;
   gap: 0.375rem;
+  margin-bottom: 0.5rem;
 }
 
+/* The brand is on the media half, which only exists from 1024px up — so this
+   is the same breakpoint `fullsplit-shell.css` reveals that half at. Below it
+   the logo above the form is the only brand on screen and stays. */
+@media (min-width: 1024px) {
+  .auth-header[data-brand-elsewhere="true"] .auth-logo {
+    display: none;
+  }
+}
+
+/* The slot caps the HEIGHT and lets the width follow the artwork.
+   It used to be a hard 56×56 square with `width: 100%` on the child, which
+   silently assumed every brand is square: a horizontal lock-up (mark + two
+   lines of type) was squeezed into the square and rendered as a scramble.
+   A square mark still comes out square — `max-width` only bounds it. */
 .auth-logo {
-  /* The slot owns the size; the logo node (inline-SVG/<img>) fills it. */
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 56px;
-  height: 56px;
+  height: 44px;
+  max-width: 100%;
   margin-bottom: 0.75rem;
-  border-radius: 14px;
   animation: authLogoIn 0.5s var(--spring-bounce) both;
 }
 
 .auth-logo > * {
-  width: 100%;
+  width: auto;
   height: 100%;
+  max-width: 100%;
   object-fit: contain;
 }
 
@@ -125,7 +153,7 @@
 .auth-form-group {
   display: flex;
   flex-direction: column;
-  gap: 0.875rem;
+  gap: var(--auth-gap);
 }
 
 .auth-input {
@@ -333,10 +361,17 @@
 
 /* ===== ERROR ===== */
 
+/* Sits directly under the input it concerns, so it reads as that field's
+   answer rather than a notice floating in the form. `align-items: flex-start`
+   keeps the icon on the first line when the message wraps.
+
+   The negative top margin pulls it inside the field's own gap: an error is
+   part of the control, not the next block down. */
 .auth-error {
   display: flex;
-  align-items: center;
+  align-items: flex-start;
   gap: 0.375rem;
+  margin-top: calc(var(--auth-gap) * -0.5);
   font-size: 0.8125rem;
   line-height: 1.4;
   color: var(--destructive);
@@ -384,10 +419,21 @@
 
 /* ===== CONSENT (passive line under the submit button) ===== */
 
+/* Quieter than the opt-in row above it, deliberately. Both were 0.75rem in
+   `--muted-foreground`, so a checkbox the visitor must decide about and a
+   legal line they need not read carried identical weight — with an error
+   between them the block read as three equal notes.
+
+   The step down is SIZE, not contrast. Fading the colour instead
+   (`--muted-foreground` at 70%) dropped it to 3.88:1 against the dark surface
+   and the a11y contract gate rejected it: `--muted-foreground` is already the
+   dimmest text token that clears AA, so anything mixed toward transparent
+   fails by construction. Legal copy is exactly the text that must stay
+   readable. */
 .auth-consent {
-  margin: 0;
+  margin: calc(var(--auth-gap) * -0.25) 0 0;
   text-align: center;
-  font-size: 0.75rem;
+  font-size: 0.6875rem;
   line-height: 1.5;
   color: var(--muted-foreground);
 }
@@ -580,39 +626,36 @@
   to { opacity: 1; }
 }
 
+/* One fade owns the whole group, via `data-visible`. Each element used to
+   carry its own inline `style={{opacity}}`, which put presentation in the
+   component and meant the mark, the message and the hint could drift apart. */
 .auth-success-content {
   display: flex;
   flex-direction: column;
   align-items: center;
   gap: 1.25rem;
+  opacity: 0;
+  transition: opacity 0.35s var(--spring-smooth);
 }
 
-.auth-success-logo {
-  /* The slot owns the size; the logo node fills it. */
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 72px;
-  height: 72px;
-  border-radius: 16px;
-  animation: authSuccessIn 0.5s var(--spring-bounce) both;
-}
-
-.auth-success-logo > * {
-  width: 100%;
-  height: 100%;
-  object-fit: contain;
+.auth-success-content[data-visible="true"] {
+  opacity: 1;
 }
 
 .auth-success-check {
-  width: 72px;
-  height: 72px;
+  width: 64px;
+  height: 64px;
   display: flex;
   align-items: center;
   justify-content: center;
-  background: hsl(142 76% 36% / 0.1);
+  /* The semantic token, not a hardcoded green: the old literal
+     `hsl(142 76% 36%)` was the one colour on this screen that could not be
+     re-themed and did not move between light and dark. `--success` is defined
+     in both themes (ui-core `theme/light.css`, `theme/dark.css`), so no
+     fallback — a missing token should surface, not be papered over. */
+  background: color-mix(in oklab, var(--success) 12%, transparent);
   border-radius: 50%;
-  color: hsl(142 76% 36%);
+  color: var(--success);
   animation: authSuccessIn 0.5s var(--spring-bounce) both;
 }
 
@@ -628,15 +671,32 @@
 }
 
 .auth-success-check svg {
-  width: 36px;
-  height: 36px;
+  width: 32px;
+  height: 32px;
+}
+
+/* Outcome first, then what the wait is for — two weights, one block, so the
+   pair reads as a single statement rather than two floating lines. */
+.auth-success-copy {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.25rem;
+  text-align: center;
 }
 
 .auth-success-text {
-  font-size: 0.9375rem;
-  font-weight: 500;
+  margin: 0;
+  font-size: 1.0625rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  color: var(--foreground);
+}
+
+.auth-success-hint {
+  margin: 0;
+  font-size: 0.8125rem;
   color: var(--muted-foreground);
-  animation: authFadeIn 0.4s 0.15s var(--spring-smooth) both;
 }
 
 /* ===== 2FA BOX ===== */

package/src/layouts/AuthLayout/styles/fullsplit-shell.css

@@ -85,6 +85,50 @@
   color: #fff;
 }
 
+/* ── Default brand content over the photo ──────────────────────────────── */
+
+/* The layout's own media-half content, used when the app passes `logo` but no
+   `sidebar` (see AuthBrandPanel). It occupies the TOP of the sidebar's
+   space-between column, leaving the bottom free for whatever an app adds
+   later; on its own it reads as a mark set on a photograph.
+
+   Colour is a literal, and deliberately so. Theme tokens answer "what colour
+   is text on OUR surface"; this text is on the consumer's photograph, which
+   the scrim below always darkens. `--foreground` would invert to near-black
+   in light mode and vanish into the picture. ui-core's styles README allows
+   raw values exactly here — branded assets and explicitly documented cases —
+   and there is no `--on-media` token to reach for. */
+.auth-brand-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  color: #fff;
+}
+
+.auth-brand-panel__mark {
+  display: inline-flex;
+  align-items: center;
+  height: 2.5rem;
+  max-width: 100%;
+}
+
+/* Same contract as `.auth-logo`: cap the height, let the width follow the
+   artwork, so a horizontal lock-up is not squeezed into a square. */
+.auth-brand-panel__mark > * {
+  width: auto;
+  height: 100%;
+  max-width: 100%;
+  object-fit: contain;
+}
+
+.auth-brand-panel__tagline {
+  margin: 0;
+  max-width: 24ch;
+  font-size: 1.125rem;
+  line-height: 1.45;
+  color: hsl(0 0% 100% / 0.82);
+}
+
 /* ── Form half (right) ─────────────────────────────────────────────────── */
 .auth-shell-fullsplit__form {
   flex: 1;

package/src/testing/index.ts

@@ -20,6 +20,14 @@ export type { AuthStep } from '@djangocfg/api/auth';
 // directly under MockAuthFormProvider without going through the full
 // AuthLayout (which mounts its own real AuthFormProvider).
 export { AuthShell } from '../layouts/AuthLayout/shells';
+// Lets a story declare the same layout-level facts AuthLayout would (e.g. that
+// the brand is already on the media half), instead of silently getting the
+// context defaults.
+export { AuthLayoutProvider, AuthSuccessScreen } from '../layouts/AuthLayout/AuthLayout';
+// The layout's own default media-half content. Stories mount `AuthShell`
+// directly, so they must supply this themselves to preview what an app that
+// passes no `sidebar` actually gets.
+export { AuthBrandPanel } from '../layouts/AuthLayout/components/shared';
 export {
   IdentifierStep,
   OTPStep,