# Pattern: Authentication (Login)

## Intent

A focused, conversion-optimized authentication page. The design is intentionally minimal — a centered card on a muted background. The user's attention goes entirely to the credentials form.

---

## When to Use

- Login page for any application
- Step-up authentication (re-verify identity)
- As a base for building: Register, Forgot Password, Reset Password, Verify Email pages

---

## Anatomy

```
┌────────────────────────────────────────────────┐
│           bg-muted (full screen)               │
│  ┌──────────────────────────────────────────┐  │
│  │           Card (max-w-sm)                │  │
│  │   ┌──────────────────────────────────┐   │  │
│  │   │ CardHeader: icon + title + desc  │   │  │
│  │   ├──────────────────────────────────┤   │  │
│  │   │ CardContent: email field         │   │  │
│  │   │              password field      │   │  │
│  │   ├──────────────────────────────────┤   │  │
│  │   │ CardFooter: full-width submit    │   │  │
│  │   └──────────────────────────────────┘   │  │
│  └──────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘
```

---

## Full Pattern Code

```tsx
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
  Input,
  Button,
  Label,
} from 'xertica-ui/ui';
import { LockIcon } from 'lucide-react';

export function LoginPage() {
  return (
    <div className="flex h-screen w-full items-center justify-center bg-muted/30">
      <Card className="w-full max-w-sm">
        <CardHeader className="text-center">
          {/* Icon badge */}
          <div className="flex justify-center mb-4">
            <div className="size-12 rounded-full bg-primary/10 flex items-center justify-center text-primary">
              <LockIcon className="size-6" />
            </div>
          </div>
          <CardTitle className="text-2xl">System Access</CardTitle>
          <CardDescription>Enter your corporate credentials to continue.</CardDescription>
        </CardHeader>

        <CardContent className="grid gap-4">
          <div className="grid gap-2">
            <Label htmlFor="email">Email</Label>
            <Input id="email" type="email" placeholder="you@company.com" required />
          </div>
          <div className="grid gap-2">
            <div className="flex items-center">
              <Label htmlFor="password">Password</Label>
              <a
                href="/forgot-password"
                className="ml-auto inline-block text-sm underline text-muted-foreground hover:text-primary"
              >
                Forgot password?
              </a>
            </div>
            <Input id="password" type="password" required />
          </div>
        </CardContent>

        <CardFooter>
          <Button className="w-full">Sign In</Button>
        </CardFooter>
      </Card>
    </div>
  );
}
```

---

## Extending This Pattern

### With react-hook-form + zod

For validation, integrate the form stack (see [Form Pattern](./form.md)):

```tsx
import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import * as z from 'zod';
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from 'xertica-ui/ui';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(6),
});
```

### Two-Column Layout (Side Image)

For marketing-style auth pages:

```tsx
<div className="grid h-screen md:grid-cols-2">
  {/* Left: branding/image */}
  <div className="hidden md:flex bg-muted items-center justify-center">
    <YourBrandingComponent />
  </div>
  {/* Right: form */}
  <div className="flex items-center justify-center">
    <Card className="w-full max-w-sm mx-6">{/* ... form ... */}</Card>
  </div>
</div>
```

---

## Composition Rules

1. **Background**: Always `bg-muted` or `bg-muted/30` — never pure white. The card itself provides the white surface.
2. **Card width**: `max-w-sm` for a single-column login. Use `max-w-md` only if adding extra fields.
3. **Submit button**: Full-width (`w-full`) in the `CardFooter`.
4. **"Forgot password?" link**: Right-aligned next to the password label using `ml-auto`.
5. **No two-column layout by default** — only add it if the design explicitly requires brand imagery.
6. **Icon in header**: Use a `rounded-full bg-primary/10 text-primary` container with a `lucide-react` icon — not an image.

---

## Related Patterns

- [Form Pattern](./form.md) — For validation with `react-hook-form` + `zod`

## Related Components

- [`Card`](../components/card.md)
- [`Input`](../components/input.md)
- [`Button`](../components/button.md)
- [`Label`](../components/label.md)