Login

이 패턴은 **화면(UI)**을 정의합니다. 버튼들을 실제 인증에 연결하는 법(패스키 등록→로그인 생애주기·웹 vs 네이티브 OS 호출·SSO·배선 레시피)은 인증 연동을 참고하세요.

AI / Consumer Implementation Contract#

AI 작업자와 소비 프로젝트는 아래 계약을 먼저 적용합니다. 세부 설명보다 이 섹션과 patterns/login.contract.json을 우선합니다. React 테스트에서는 @wds/ui-web/testing의 assertLoginPatternCompliance(preset, screen)으로 같은 계약을 검증합니다.

MUST#

• 단일 패널 — 로그인은 LoginSurface 하나로 구성합니다. 전체 화면·모달·사이드 패널 어디에 넣어도 인증 표면은 하나입니다.
• 최대 폭 390px — LoginSurface size="sm"을 사용합니다. 인증 표면 자체는 데스크탑에서도 390px를 넘지 않습니다.
• 정렬 고정 — 브랜드·제목·설명은 중앙 정렬, 입력 라벨·필드·오류는 좌측 정렬입니다.
• 입력 배선 — FormField와 Input을 조합해 보이는 라벨, htmlFor/id, aria-describedby, aria-invalid를 유지합니다.
• 타이포 위계 — 제목, primary CTA, 방식 버튼은 medium; 설명·footer는 regular 기준입니다.
• Primary CTA는 하나 — 한 로그인 표면 안의 채움 primary action은 1개만 둡니다.
• 방식 버튼 위계 — passkey/SSO는 AuthMethodButton, Apple/Google/Microsoft는 ProviderButton으로 풀폭 동등 노출합니다.
• 기업 로그인 구분 — 기업 로그인은 조직 SSO와 관리자 문의가 중심입니다. 공개 가입 권한은 제품/조직 관리자가 소유합니다.
• 2FA/복구 분리 — 인증 앱 코드와 복구 코드는 첫 로그인 화면에 섞지 않고 별도 단계 표면으로 전환합니다.
• 접근성 — LoginSurface는 이름 있는 region, 입력은 보이는 라벨, 오류는 live region, OTP는 OneTimeCodeInput, 식별자는 가능한 경우 autocomplete="username webauthn"을 사용합니다.

SHOULD#

• 범용 로그인은 이메일·비밀번호를 기본값으로 두고 passkey와 provider 버튼을 같은 LoginMethods 그룹에 배치합니다.
• 패스키 준비 프리셋은 이메일 자동완성(username webauthn)과 AuthMethodButton method="passkey"를 함께 제공합니다.
• 인증 실패는 어느 필드가 틀렸는지 말하지 않는 제너릭 FormMessage variant="error"로 CTA 바로 위에 둡니다.
• 계정 잠금은 FormMessage variant="warning" 또는 동등한 live status를 쓰고, 모든 CTA를 비활성화합니다.
• 소비 프로젝트 테스트에는 아래 한 줄을 추가합니다.

assertLoginPatternCompliance('enterprise', screen);

NEVER#

• 마케팅 split 패널, 제품 소개 카드, 캠페인 이미지 패널을 로그인 패턴 내부에 넣지 않습니다.
• 한 화면에 primary CTA를 2개 이상 두지 않습니다.
• passkey/SSO/provider 버튼을 작은 링크, tertiary action, 접힌 메뉴로 낮추지 않습니다.
• 기업 로그인에 Apple/Google/Microsoft provider 버튼 또는 계정 만들기 CTA를 넣지 않습니다.
• 기업 로그인 footer를 공개 가입으로 보내지 않습니다. footer는 관리자에게 문의입니다.
• 2FA/복구 코드 입력을 이메일·비밀번호·provider 버튼과 같은 첫 로그인 화면에 섞지 않습니다.
• placeholder를 라벨 대체로 쓰거나, 비밀번호 붙여넣기/비밀번호 매니저를 막지 않습니다.

프리셋별 구현 계약#

React 소비 레시피#

import {
  AuthMethodButton,
  Button,
  FormField,
  Input,
  LoginMethods,
  LoginSurface,
  TextLink,
} from '@wds/ui-web';

export function EnterpriseLoginRecipe() {
  return (
    <LoginSurface
      brand={<ProductLogo />}
      title="기업 로그인"
      subtitle="회사 계정으로 계속하세요."
      footer={<TextLink href="/help/access">관리자에게 문의</TextLink>}
      size="sm"
    >
      <LoginSurface.Body>
        <FormField label="회사 이메일">
          <Input type="email" autoComplete="username webauthn" />
        </FormField>
        <FormField label="비밀번호">
          <Input type="password" autoComplete="current-password" />
        </FormField>
        <LoginMethods>
          <AuthMethodButton method="sso" />
          <AuthMethodButton method="passkey" />
        </LoginMethods>
      </LoginSurface.Body>
      <LoginSurface.Actions>
        <Button type="submit" fullWidth>
          로그인
        </Button>
      </LoginSurface.Actions>
    </LoginSurface>
  );
}

import {
  AuthMethodButton,
  Button,
  FormField,
  Input,
  LoginMethods,
  LoginSurface,
  ProviderButton,
  TextLink,
} from '@wds/ui-web';

export function GenericLoginRecipe() {
  return (
    <LoginSurface
      brand={<ProductLogo />}
      title="로그인"
      subtitle="계정으로 계속하세요."
      footer={<TextLink href="/signup">계정 만들기</TextLink>}
      size="sm"
    >
      <LoginSurface.Body>
        <FormField label="이메일">
          <Input type="email" autoComplete="username webauthn" />
        </FormField>
        <FormField label="비밀번호">
          <Input type="password" autoComplete="current-password" />
        </FormField>
        <LoginMethods>
          <AuthMethodButton method="passkey" />
          <ProviderButton provider="apple" fullWidth />
          <ProviderButton provider="google" fullWidth />
          <ProviderButton provider="microsoft" fullWidth />
        </LoginMethods>
      </LoginSurface.Body>
      <LoginSurface.Actions>
        <Button type="submit" fullWidth>
          로그인
        </Button>
      </LoginSurface.Actions>
    </LoginSurface>
  );
}

import {
  Button,
  LoginSurface,
  OneTimeCodeInput,
  TextLink,
} from '@wds/ui-web';

export function TwoFactorRecipe() {
  return (
    <LoginSurface
      brand={<ProductLogo />}
      title="인증 앱 확인"
      subtitle="인증 앱의 6자리 코드를 입력하세요."
      footer={<TextLink href="/recovery-code">복구 코드 사용</TextLink>}
      size="sm"
    >
      <LoginSurface.Body>
        <OneTimeCodeInput length={6} name="otp" aria-label="인증 코드" />
      </LoginSurface.Body>
      <LoginSurface.Actions>
        <Button type="submit" fullWidth>
          확인
        </Button>
      </LoginSurface.Actions>
    </LoginSurface>
  );
}

import { render, screen } from '@testing-library/react';
import { assertLoginPatternCompliance } from '@wds/ui-web/testing';

render(<EnterpriseLoginRecipe />);
assertLoginPatternCompliance('enterprise', screen);

데모#

상단 컨트롤로 세 축을 살펴봅니다 — 프리셋(범용 · 패스키 준비 · 기업 로그인 · 소셜 로그인 · 고보안 · 재인증), 상태(라이브 · 로딩 · 인증 실패 · 계정 잠금 · 인증 앱 · 복구 코드 · 성공 · 패스키 등록), 옵션(Apple·Google·Microsoft 계정 연동 표시/숨김). 실제 인증은 없습니다(UI Reference). 라이브에서 빈 값 제출은 필드 오류를 보여주고, 유효 제출·패스키·SSO·Provider 버튼은 성공을 시뮬레이션합니다. 프리셋·상태처럼 선택지가 길거나 모바일 한 줄에서 넘칠 수 있는 데모 선택기는 SegmentedButton이 아니라 ChipGroup을 사용합니다. 짧고 고정된 2~4개 선택지만 한 줄에 안정적으로 들어갈 때 SegmentedButton을 씁니다.

언제 로그인을 요구하나#

로그인 화면을 어떻게 만드느냐보다 언제 요구하느냐가 먼저입니다.

• 게스트 우선 — 로그인을 가능한 한 늦춥니다. 둘러보기·열람으로 가치를 먼저 경험하게 하고, 계정이 꼭 필요한 동작(저장·공유·결제)에서만 요구합니다.
• 가치 교환 — “가치를 주는 대가로만” 로그인을 요청합니다. 진입 즉시 벽을 세우지 않습니다.
• 계정 최소화 — 핵심 기능이 계정을 요구하지 않으면 계정 생성을 강제하지 않습니다.
• 삭제 진입점 의무 — 계정 생성을 돕는다면 삭제(비활성화 아님) 경로도 앱 안에서 제공해야 합니다.
• provider 동등성 — 서드파티 로그인(Google·Microsoft 등)만으로 계정을 만드는 진입은 동급의 대안(Sign in with Apple·자체 계정)을 함께 둡니다.

이 패턴은 “로그인 표면”의 정본일 뿐, 로그인을 띄울지 말지는 제품이 위 정책으로 결정합니다.

구성#

로그인 화면의 정본은 단일 인증 표면입니다. 제품 브랜드·캠페인 메시지·마케팅 이미지는 페이지 배경이나 상위 레이아웃에서 처리하고, 패턴 자체는 인증에 필요한 입력과 선택지만 담습니다.

데모의 로고는 실제 WDS·제품 로고가 아니라 서비스 로고 자리표시자입니다. 제품은 이 슬롯에 자사 심볼, 앱 아이콘, 조직 브랜드를 넣고, 패턴은 로고의 모양을 강제하지 않습니다.

아트디렉션 계약#

로그인 표면은 기능 옵션보다 먼저 읽는 순서와 시각 리듬이 고정되어야 합니다. 아래 계약을 깨면 구글·애플·마이크로소프트 계정 연동을 붙여도 화면이 불안정해집니다.

이 계약은 레퍼런스 조사의 기본 산출물에도 포함됩니다. 새 로그인 변형을 제안할 때는 기능 흐름뿐 아니라 레이아웃·정렬·간격·여백·타이포·버튼 위계·반응형 검증을 함께 기록해야 합니다.

적응형 동작#

패턴은 같은 단일 패널을 재사용합니다. 상위 화면이 넓어져도 인증 표면 자체는 390px를 넘지 않고, 좁은 배치에서는 padding·OTP 칸·간격만 컨테이너 폭에 맞춰 축소합니다.

입력·CTA의 터치 타깃은 유지하고, 동일 패턴을 모달·사이드 패널·전체 화면 어디에 배치해도 깨지지 않습니다. 인증 앱·복구 코드·패스키 등록 권유도 같은 단일 표면 안에서 단계 전환됩니다. 코드 입력은 모바일에서도 한 줄을 유지하되, 칸과 간격만 컨테이너 폭에 맞춰 축소합니다.

조합 모델#

로그인은 이제 “식별자 우선”과 “단일 화면” 중 하나를 고르는 문제가 아닙니다. 제품 정책에 따라 한 인증 표면의 슬롯을 켜고 끕니다. 기본값은 이메일·비밀번호를 바로 사용할 수 있는 표면이며, 패스키·SSO·소셜 로그인은 동등한 대체 방식으로 붙습니다. 인증 앱과 복구 코드는 1차 로그인 방식이 아니라 2차 인증/복구 단계입니다.

패스키 conditional UI — 패스키의 1차 발견 경로는 명시 버튼만이 아니라 이메일 필드 autofill입니다. 식별자 입력에 autocomplete="username webauthn"을 주면 브라우저가 사용 가능한 패스키를 자동완성 목록에 함께 띄웁니다. AuthMethodButton method="passkey"는 이 conditional UI를 보완·명시하는 경로로 둡니다.

프리셋#

프리셋은 별도 패턴이 아니라 옵션 묶음입니다. 제품팀은 하나를 시작점으로 삼고 필요한 슬롯만 조정합니다.

로그인 프로세스#

범용 로그인과 기업 로그인은 같은 인증 표면을 쓰지만 계정 생성 권한이 다릅니다.

기업 로그인은 공개 회원가입 플로우로 이어지면 안 됩니다. 계정은 조직 관리자가 초대·발급하거나 IdP/SCIM 같은 조직 프로비저닝으로 생성합니다. 사용자가 접근 권한이 없거나 조직 도메인이 매칭되지 않는 경우에는 가입 CTA 대신 관리자 문의, 헬프데스크, 접근 요청 흐름으로 보냅니다.

공통 로그인 진행#

보조 프로세스#

어드민 콘솔 연결#

로그인 패턴은 어드민 콘솔의 보안 기능과 이어져야 합니다. 콘솔의 인증 & 접근 영역은 패스키·2FA·조직 SSO를 관리하고, 로그인 알림은 새 기기·비정상 위치·반복 실패를 알려줍니다. 비밀번호 영역은 변경, 만료 정책, 재설정 링크를 담당하며, 활성 세션은 현재 기기와 의심 세션 회수를 보여줍니다.

이 구조를 쓰면 로그인 화면은 얇게 유지하면서도, 계정 복구·패스키 등록·2FA 설정·세션 보안 같은 운영 프로세스는 어드민 콘솔 또는 계정 설정으로 자연스럽게 이어집니다.

변형#

같은 인증 표면을 맥락에 따라 배치합니다 — 컴포넌트·상태는 공유하고 주변 셸만 바꿉니다.

modal·SSO landing은 같은 표면을 다른 셸에 끼워 재사용합니다 — 새 컴포넌트를 만들지 않습니다.

상태#

데모의 상태 컨트롤로 로딩·인증 실패·계정 잠금·MFA·복구·패스키 등록 권유를 강제 표시해 검수할 수 있습니다.

실제 인증 로직은 포함하지 않습니다 — 패턴은 UI Reference만 제공합니다(MASTER_PLAN Portal Boundary). 제품은 이 표면에 자사 인증 흐름을 연결합니다.

모션#

전환은 흐름을 보조할 뿐 주의를 끌지 않습니다 — spring 토큰을 그대로 소비합니다.

transform·opacity만 애니메이트해 레이아웃을 흔들지 않습니다(컴포지터 친화). prefers-reduced-motion: reduce면 모든 전환을 끄고 즉시 정적으로 표시합니다(WCAG 2.3.3).

콘텐츠·보안#

외부 기준#

접근성#

WCAG 2.2 AA를 기준으로, 로그인 특화 신규 기준(§3.3.8 Accessible Authentication)을 명시적으로 만족시킵니다.

사용 컴포넌트#

Input(leadingIcon·trailingIcon·invalid) · FormField(error) · Button(primary·secondary·ghost·fullWidth·loading) · Checkbox · TextLink · FormMessage(error·warning, Tier 2) · ChipGroup(긴 데모 선택 컨트롤) · LoginSurface · AuthMethodButton · LoginMethods · ProviderButton · OneTimeCodeInput. 전부 06 컴포넌트의 실물을 그대로 조합했습니다. LoginSurface는 패키지로 배포되는 표면 recipe이고, 프리셋·상태·실제 인증 프로세스는 제품이 조합합니다.

토큰#

패턴 전용 토큰은 두지 않고 semantic 토큰을 직접 소비합니다.

백엔드 연동 (P6)#

위 패턴 데모는 UI Reference라 실제 인증이 없습니다. P6 Backend Base의 core-api와 실제로 통신하는 데모는 아래에 있습니다 — 루트에서 make stack-up으로 로컬 풀스택을 먼저 띄워야 동작합니다(진입점 localhost:58080, Nginx 리버스 프록시).

시드 계정은 demo 프로파일이 만듭니다 — 이메일 admin@wiz-factory.com, 비밀번호는 infra/docker/.env의 WDS_DEMO_ADMIN_PASSWORD. 자세한 API 계약은 BACKEND_GUIDE(P6 문서)를 참고하세요.