Platform Docs

Appearance

AuthCard export·prop 사용 현황 조사 ​

1. 조사 대상 ​

조사 기준은 feat/antd-phase-2-components 브랜치이며, main과 동일한 Phase 0·1 병합 결과 및 Phase 2 기준선 문서를 포함한다. 저장소 전체에서 AuthCard, 인증 입력, submit callback, password 관련 심볼과 CSS selector를 검색했다.

2. 실제 export 경로 ​

AuthCard는 별도 파일이 아니라 packages/ui-react/src/index.tsx에 직접 구현되어 있다.

ts
export type AuthCardProps = { ... };
export function AuthCard(props: AuthCardProps) { ... }

packages/ui-react/package.json의 package export는 다음과 같다.

json
{
  ".": {
    "types": "./dist/index.d.ts",
    "default": "./dist/index.js"
  },
  "./styles.css": "./dist/styles.css"
}

따라서 소비 포털의 공개 사용 경로는 다음과 같다.

ts
import { AuthCard, type AuthCardProps } from "@hohyun94/portal-foundation";

현재 저장소에는 AuthCard를 다른 source 파일이나 테스트에서 import해 사용하는 코드가 없다. 검색 결과는 구현부, Phase 계획 문서, 기준선 문서와 AuthCard CSS 정의에 한정된다. 따라서 현재 저장소에서 확인 가능한 소비 계약은 타입 선언과 구현 동작이며, 실제 Process Center·Guide Center·Document Library 소비 코드는 이 저장소 외부에 있을 가능성이 있다.

3. 현재 AuthCardProps ​

Prop타입필수 여부현재 동작
eyebrowstring필수BrandMark label의 기본값과 eyebrow 텍스트로 사용
titleReactNode필수h1#portal-auth-title로 렌더링
descriptionReactNode필수설명 paragraph로 렌더링
actionLabelstring필수action button/link의 label
actionIconReactNode선택아이콘이 있으면 렌더링, 없으면 → 표시
continueHrefstring선택있으면 <a> action으로 렌더링
onContinue() => void선택continueHref가 없을 때 button callback
noticeReactNode선택notice 영역에 렌더링
errorReactNode선택role="alert" 오류 paragraph로 렌더링
footerLeftReactNode선택footer 왼쪽 영역
footerRightReactNode선택footer 오른쪽 영역
brandLabelstring선택BrandMark의 accessible label, 기본값은 eyebrow
disabledboolean선택기본값 false; action 비활성화
childrenReactNode선택divider와 action 사이의 사용자 제공 콘텐츠

4. 현재 렌더링 계약 ​

현재 markup 순서는 다음과 같다.

text
section.pf-auth-card[aria-labelledby="portal-auth-title"]
├── BrandMark
├── p.pf-auth-card__eyebrow
├── h1#portal-auth-title.pf-auth-card__title
├── p.pf-auth-card__description
├── div.pf-auth-card__divider
├── children
├── a/button.pf-auth-card__action
├── div.pf-auth-card__notice? 
├── p.pf-auth-card__error[role="alert"]?
└── footer.pf-auth-card__footer?

Action 분기 ​

continueHref가 있으면 anchor가 렌더링된다.

  • href={continueHref}
  • aria-disabled={disabled || undefined}
  • disabled 상태에서 click event의 기본 동작을 차단
  • disabled HTML attribute는 사용하지 않음

continueHref가 없으면 button이 렌더링된다.

  • type="button"
  • disabled={disabled}
  • onClick={onContinue}

현재 타입은 continueHref와 onContinue의 상호 배타성을 강제하지 않는다. 두 값이 모두 없거나 모두 있어도 타입 단계에서 막지 않는다.

5. CSS selector 계약 ​

packages/ui-react/styles/styles.css에 다음 selector가 존재한다.

Selector역할
.pf-auth-card카드 외곽, 폭, border, surface, shadow
.pf-auth-card__eyebroweyebrow 텍스트
.pf-auth-card__title제목
.pf-auth-card__description설명
.pf-auth-card__dividerdivider
.pf-auth-card__action공통 action link/button
.pf-auth-card__action-icon제공된 action icon
.pf-auth-card__arrow기본 arrow
.pf-auth-card__notice안내 영역
.pf-auth-card__error오류 영역
.pf-auth-card__footerfooter 영역

Action focus selector는 다음과 같이 공통 focus ring을 제공한다.

css
.pf-auth-card__action:focus-visible {
  outline: 2px solid var(--pf-accent);
  outline-offset: 3px;
}

Disabled anchor는 다음 selector로 시각 처리된다.

css
.pf-auth-card__action[aria-disabled="true"] {
  cursor: not-allowed;
  opacity: .6;
}

6. 접근성 계약 ​

현재 구현에서 확인된 접근성 동작은 다음과 같다.

  • 최상위 영역은 section이다.
  • section은 aria-labelledby="portal-auth-title"를 가진다.
  • 제목은 h1#portal-auth-title이다.
  • 오류는 p[role="alert"]로 렌더링된다.
  • BrandMark는 role="img"와 aria-label을 가진다.
  • action icon과 기본 arrow는 aria-hidden="true"다.
  • disabled link는 aria-disabled="true"를 사용한다.
  • disabled button은 native disabled attribute를 사용한다.

Phase 2.1 전환 시 Card와 Form을 도입하더라도 이 semantic heading, alert, focus, disabled 계약을 유지해야 한다.

현재 구현의 주의점은 id="portal-auth-title"가 고정되어 있다는 것이다. 한 화면에 AuthCard가 둘 이상 렌더링되면 duplicate id와 잘못된 aria-labelledby 연결이 발생할 수 있으므로, Ant Design 전환 시 useId() 또는 안정적인 id prop 도입을 검토한다.

7. 실제 사용 현황 결론 ​

저장소 내부의 실제 사용처는 확인되지 않았다.

구분결과
구현packages/ui-react/src/index.tsx 1곳
공개 타입AuthCardProps 직접 export
package export@hohyun94/portal-foundation root export를 통해 노출
테스트 사용현재 전용 AuthCard 테스트 없음
소비 포털 import이 저장소 검색 범위에서는 없음
관련 문서Ant Design adoption plan 및 Phase 2 기준선 문서
CSSpackages/ui-react/styles/styles.css에 전용 selector 13개

8. Phase 2.1 구현 권고 ​

  1. 기존 AuthCardProps 이름과 필수 prop을 우선 유지한다.
  2. AuthCard 전용 테스트를 추가해 현재 markup과 callback 동작을 먼저 고정한다.
  3. continueHref와 onContinue의 상호 배타성 또는 우선순위를 명시한다.
  4. fixed portal-auth-title id를 useId() 기반으로 변경하되, 기존 selector와 heading semantics는 유지한다.
  5. Card, Form, Input, Alert, Button은 내부 구현으로만 사용하고 Ant Design 타입을 public API에 직접 노출하지 않는다.
  6. children 위치를 유지해 소비 포털의 인증 입력·OAuth 위젯 삽입 호환성을 보장한다.
  7. link action의 aria-disabled 및 click 차단과 button action의 native disabled를 각각 테스트한다.
  8. 기존 .pf-auth-card* class를 유지하거나, 제거가 필요하면 compatibility class를 함께 렌더링한다.
  9. 외부 소비 포털 코드가 저장소에 없으므로, 실제 migration 전에는 소비 포털 저장소에서 AuthCard import와 prop 사용을 별도로 검색해야 한다.

9. 권장 Phase 2.1 테스트 케이스 ​

  • 필수 prop과 기본 markup 렌더링
  • children이 divider와 action 사이에 렌더링되는지 확인
  • continueHref가 있으면 anchor action이 생성되는지 확인
  • continueHref가 없으면 button action과 onContinue가 동작하는지 확인
  • link disabled 상태에서 navigation이 차단되는지 확인
  • button disabled 상태에서 callback이 호출되지 않는지 확인
  • notice와 error 표시
  • error의 role="alert" 유지
  • action icon과 arrow의 aria-hidden 유지
  • brandLabel fallback 동작
  • unique heading id와 aria-labelledby 연결
  • light/dark Provider 아래에서 token 및 class 계약 유지