# Authentication shells

Authentication should feel intentional without competing with the task of gaining access. Use one of two shells according to the length and importance of the flow.

## Primary access: branded split shell

Use the split shell for primary sign-in and account creation when a product benefits from a stronger first impression.

### Supporting pane

The supporting pane may contain:

- the product mark and name;
- one concise positioning statement;
- one short supporting sentence;
- a quiet security or trust statement.

Keep this content product-owned. Do not add marketing navigation, carousels, release announcements, testimonials, or time-sensitive campaign content. Authentication must remain the obvious task.

The pane may use a product surface or restrained gradients, but text must retain sufficient contrast and the presentation must respect reduced-motion preferences.

### Form pane

- Center a form no wider than `--auth-form-max-width` (30rem).
- Start with a clear title and one-line instruction.
- Put identity-provider buttons before the email/password fields when they are supported.
- Visually label the separator between provider and credential paths.
- Keep recovery and registration routes visible without making them more prominent than Sign in.
- Preserve space for inline errors and loading labels.

## Utility flows: compact card shell

Use a compact centered card for password recovery, password reset, email verification, invitations, two-factor challenges, and re-authentication.

- Keep one clear task per card.
- Use the same form controls and action hierarchy as primary access.
- Provide a direct route back to sign in when appropriate.
- Do not retain an empty supporting pane simply to match the primary shell.

## Responsive behavior

At narrow widths, remove the supporting pane and show the form pane full width. Do not place its marketing message above the form, where it would delay access. Keep the product mark available in the form or page header when identity is needed.

The form remains constrained by `--auth-form-max-width`, with comfortable page padding and no horizontal scrolling. Provider actions may wrap or stack when labels cannot fit.

## Security and usability

1. Use semantic inputs with correct `type` and `autocomplete` values.
2. Keep password-manager integration intact; do not block paste.
3. Password visibility controls need an accessible name and must not move focus.
4. Associate field errors using `aria-describedby` and announce submission errors without clearing valid input.
5. Preserve recovery routes even when single sign-on is preferred.
6. Keep submission button dimensions stable during loading and prevent repeated requests.
7. Do not reveal whether an account exists in recovery confirmation copy unless the product’s security policy explicitly permits it.

## Product boundary

The design system owns layout variants, responsive behavior, form width, hierarchy, and accessibility expectations. Each product owns branding, identity providers, eligibility, authentication policy, legal links, security wording, and support routes.