Platform Docs

Appearance

Ant Design Phase 0·1 초기 기준선 ​

대상 브랜치: feat/antd-phase-0-1-bootstrap 기준 브랜치: main

이 문서는 Ant Design 전면 도입의 Phase 0(기준선 확보)과 Phase 1(의존성·스타일 기반 정리)을 시작하기 위한 체크리스트다.

Phase 0. 기준선 확보 ​

저장소와 패키지 ​

  • [ ] main 기준 저장소 상태와 최근 커밋을 기록한다.
  • [ ] pnpm workspace 패키지 목록을 확인한다.
  • [ ] packages/ui-react/src/index.tsx의 공개 export 목록을 동결한다.
  • [ ] 세 소비 포털의 portal-foundation 버전과 사용 중인 공통 컴포넌트를 수집한다.

품질 명령 ​

아래 명령을 로컬 또는 CI에서 실행하고 결과를 PR 설명에 기록한다.

bash
pnpm install --frozen-lockfile
pnpm -r build
pnpm --filter @hohyun94/portal-foundation check
pnpm --filter @hohyun94/portal-foundation test
  • [ ] 의존성 설치 결과를 기록한다.
  • [ ] 전체 workspace build 결과를 기록한다.
  • [ ] ui-react typecheck 결과를 기록한다.
  • [ ] ui-react test 결과를 기록한다.
  • [ ] 실패한 기존 테스트와 Ant Design 전환으로 새로 생긴 실패를 구분한다.

시각·동작 기준선 ​

다음 상태를 전환 전 기준 화면으로 저장한다.

  • [ ] light theme
  • [ ] dark theme
  • [ ] PortalShell expanded
  • [ ] PortalShell collapsed
  • [ ] loading / empty / error
  • [ ] desktop / mobile viewport
  • [ ] keyboard focus 및 주요 메뉴 탐색

검증 대상은 PortalShell, PortalAdminShell, PortalButton, StatusBadge, AuthCard, ThemePicker, dataShells다.

Phase 1. 의존성·스타일 기반 ​

의존성 정책 ​

  • [ ] 지원할 Ant Design major/minor 버전을 결정한다.
  • [ ] React 18 이상 peer dependency와 호환성을 확인한다.
  • [ ] antd 의존성 위치를 결정한다.
  • [ ] @ant-design/icons의 개별 import 규칙을 확정한다.
  • [ ] 전체 icon module import를 금지한다.
  • [ ] ESM tree-shaking 결과와 bundle size 기준을 측정한다.

초기 의존성 추가 대상은 packages/ui-react/package.json이다.

json
{
  "dependencies": {
    "antd": "<결정된 버전>",
    "@ant-design/icons": "<결정된 버전>"
  }
}

실제 버전은 Phase 1 구현 PR에서 저장소의 React·TypeScript·빌드 환경을 확인한 뒤 확정한다. 이 브랜치에서는 버전을 임의로 고정하지 않는다.

스타일 정책 ​

  • [ ] antd/dist/reset.css 적용 여부를 결정한다.
  • [ ] 기존 packages/ui-react/styles/styles.css와 reset CSS의 import 순서를 결정한다.
  • [ ] CSS layer 또는 selector scope 전략을 결정한다.
  • [ ] 포털 CSS가 Ant Design 기본 스타일을 전역 덮어쓰는 위치를 조사한다.
  • [ ] light/dark CSS 변수와 Ant Design token 매핑 경계를 문서화한다.
  • [ ] 스타일 변경 전후의 specificity와 cascade 충돌을 확인한다.

Phase 1 완료 기준 ​

Phase 1은 다음 조건을 충족할 때 완료한다.

  1. antd와 @ant-design/icons의 버전 정책이 결정되어 있다.
  2. 개발·build·typecheck·test 환경에서 Ant Design import가 가능하다.
  3. CSS reset과 기존 styles의 적용 순서가 결정되어 있다.
  4. 기존 UI 회귀 기준선이 저장되어 있다.
  5. bundle size 측정 방식과 허용 증가량이 정해져 있다.
  6. Phase 2의 PortalConfigProvider 구현을 시작할 수 있다.

PR 운영 규칙 ​

  • Phase 0 기준선 문서와 Phase 1 의존성 변경은 별도 커밋으로 나눈다.
  • 공개 API 변경은 이 PR에서 하지 않는다.
  • PortalShell 전체 교체는 이 PR에 포함하지 않는다.
  • 기준선 명령의 실패는 원인과 후속 이슈를 PR 설명에 남긴다.
  • merge 전 CI와 리뷰어의 토큰·스타일 정책 확인을 완료한다.

다음 PR ​

다음 구현 PR에서는 PortalConfigProvider, mapPortalTokensToAntdTheme, antd dependency, reset CSS 정책을 실제 코드로 추가한다. 이후 PortalButton을 첫 번째 Ant Design 기반 컴포넌트로 전환한다.