Ant Design 전면 도입 작업계획

1. 문서 목적

이 문서는 portal-foundation의 공통 React UI를 Ant Design 기반으로 전환하기 위한 구현 순서, 범위, 설계 원칙, 검증 기준을 정의한다. 목표는 범용 UI의 유지보수 부담을 줄이면서도 포털 고유 정책과 공개 API의 안정성을 유지하는 것이다.

2. 최종 방향

packages/ui-react의 공통 UI 기본 구현체는 Ant Design으로 통일한다. packages/design-tokens는 포털 디자인의 원본 토큰으로 유지하고, packages/theme-client와 새 PortalConfigProvider가 이를 Ant Design 테마 설정으로 변환한다.

Ant Design에 존재하는 범용 요소는 직접 재구현하지 않는다. 포털에만 필요한 셸, 권한 메뉴, 업무 상태, 디렉터리 관리, FileStore 첨부파일, 테마 정책과 같은 도메인 컴포넌트는 portal-foundation이 소유한다. 이 컴포넌트는 Ant Design의 기반 컴포넌트를 조합해 구현한다.

text

포털 애플리케이션
        │
        ▼
portal-foundation 공개 API
  PortalShell / PortalTable / PortalForm / StatusBadge ...
        │
        ▼
Ant Design + @ant-design/icons
        │
        ▼
design-tokens / theme-client

3. 적용 범위

영역	처리 방침
`packages/ui-react`	Ant Design 의존성 추가, Provider·컴포넌트·레이아웃 전환
`packages/design-tokens`	원본 토큰 유지, Ant Design 토큰 매핑에 필요한 값 보강
`packages/theme-client`	테마 선택·저장 정책 유지, Provider 연동
`packages/directory-sync`	UI와 독립적으로 유지
`packages/filestore-adapter`	서버 계약 유지
`packages/editor-core`	UI 전환과 분리
`packages/operations-core`	UI 전환과 분리
`packages/runtime-core`	런타임 계약 유지
`packages/security-core`	보안 계약 유지

4. 지켜야 할 설계 원칙

4.1 디자인 토큰의 소유권

Ant Design의 기본 토큰을 포털 디자인의 원본으로 사용하지 않는다. 포털의 색상, 표면, 간격, 타이포그래피, 모서리 반경, 상태색은 design-tokens가 소유한다. Ant Design은 매핑된 값을 렌더링에 사용한다.

4.2 공개 API 안정성

기존 PortalShell, PortalAdminShell, PortalButton, StatusBadge, AuthCard, ThemePicker 등의 공개 API를 우선 유지한다. 내부 구현을 Ant Design으로 교체하되, 소비 포털이 한 번에 대규모 수정되지 않도록 호환 계층을 둔다.

4.3 도메인 정책의 중앙화

권한 메뉴, 디렉터리 사용자, 업무 상태, FileStore 메타데이터, 포털 오류 메시지와 같은 정책은 애플리케이션마다 흩어지지 않도록 portal-foundation에서 관리한다.

4.4 controlled/uncontrolled 규칙

셸 접기 상태, 테마 선택, 폼 초기값, 모달 표시 상태 등은 controlled와 uncontrolled 사용 방식을 명확히 정의한다. 각 컴포넌트는 내부 상태를 기본값으로 제공하되, 외부 값과 변경 콜백이 함께 전달되면 controlled 모드로 동작한다.

4.5 단계별 교체

새 컴포넌트를 별도로 병행 개발해 중복 체계를 만들지 않는다. 기존 컴포넌트의 내부 구현을 단계적으로 교체하고, 기존 테스트와 공개 API를 기준으로 회귀를 검증한다.

5. 권장 디렉터리 구조

text

packages/ui-react/src/
├── providers/
│   ├── PortalConfigProvider.tsx
│   ├── antdTheme.ts
│   └── index.ts
├── layouts/
│   ├── PortalShell/
│   ├── PortalAdminShell/
│   └── index.ts
├── components/
│   ├── PortalButton/
│   ├── AuthCard/
│   ├── StatusBadge/
│   ├── ThemePicker/
│   └── index.ts
├── navigation/
│   ├── PortalMenu/
│   ├── MenuManagement/
│   └── index.ts
├── data-display/
│   ├── PortalTable/
│   ├── DataShell/
│   ├── ContentComponents/
│   └── index.ts
├── forms/
│   ├── PortalForm/
│   ├── PortalField/
│   └── index.ts
├── feedback/
│   ├── PortalEmpty/
│   ├── PortalResult/
│   ├── PortalSkeleton/
│   └── index.ts
├── attachments/
│   ├── AssetAttachmentList/
│   └── index.ts
├── icons/
│   └── index.ts
└── index.ts

기존 파일을 한 번에 삭제하지 않는다. 초기 단계에서는 기존 파일이 새 디렉터리의 구현을 re-export할 수 있도록 두어 import 경로를 보존한다. 모든 소비 포털이 새 경로로 이동한 뒤에만 legacy 파일을 제거한다.

6. 단계별 실행 순서

Phase 0. 기준선 확보

현재 main의 빌드, 타입 검사, 테스트 결과를 기준선으로 저장한다. 기존 ui-react 공개 export와 각 포털에서 사용하는 컴포넌트·prop을 목록화한다.

작업 항목

pnpm install 및 전체 workspace build 확인
packages/ui-react의 check, test 실행
src/index.tsx의 모든 export 목록 작성
세 포털에서 사용하는 공통 컴포넌트와 prop 사용 현황 조사
현재 light/dark 테마와 주요 화면의 스크린샷 확보
Ant Design 버전과 React peer dependency 호환성 결정

완료 기준

기준선 명령과 결과가 문서 또는 CI 로그에 남아 있다.
호환성을 깨면 안 되는 공개 API 목록이 확정되어 있다.
전환 전 시각 기준 화면이 확보되어 있다.

Phase 1. 의존성 및 스타일 기반 정리

ui-react에 antd와 필요한 @ant-design/icons를 추가한다. 아이콘은 개별 import를 사용하고 전체 아이콘 모듈 import를 금지한다. reset 스타일과 기존 styles.css의 적용 순서를 결정한다.

작업 항목

antd 의존성 추가
@ant-design/icons 의존성 추가
ESM tree-shaking 및 번들 결과 확인
antd/dist/reset.css 적용 여부 결정
기존 CSS selector와 Ant Design selector 충돌 조사
CSS layer 또는 명시적 import 순서 도입

완료 기준

개발·빌드·테스트 환경에서 Ant Design을 import할 수 있다.
기존 화면의 전역 CSS가 예기치 않게 깨지지 않는다.
번들 크기 증가량이 허용 범위 내로 정의된다.

Phase 2. 토큰 매핑과 `PortalConfigProvider` 구축

design-tokens에서 사용하는 포털 토큰을 Ant Design theme.token, components, algorithm 설정으로 변환한다. 테마 적용의 진입점을 하나로 통합한다.

예상 사용 형태는 다음과 같다.

tsx

<PortalConfigProvider
  theme="light"
  locale={locale}
  componentSize="middle"
>
  <PortalApp />
</PortalConfigProvider>

작업 항목

mapPortalTokensToAntdTheme 함수 작성
light/dark algorithm 정책 결정
colorPrimary, 상태색, 배경색, 텍스트색 매핑
radius, control height, font, padding, motion 설정
Button, Input, Select, Table, Card, Layout 등 컴포넌트별 토큰 정의
App 또는 App.useApp() 기반 message·notification·modal 정책 검토
theme-client의 저장·복원 lifecycle 연결
SSR 또는 hydration 환경에서의 스타일 처리 확인

완료 기준

포털별 테마를 Provider 하나로 적용할 수 있다.
light/dark 전환이 새로고침 후에도 정책대로 복원된다.
토큰 매핑 테스트가 존재한다.
소비 포털이 Ant Design의 전역 Provider를 직접 구성하지 않아도 된다.

Phase 3. 기반 컴포넌트 전환

작고 영향 범위가 명확한 컴포넌트부터 전환한다. 이 단계에서는 기존 이름과 prop을 최대한 유지한다.

전환 대상

PortalButton → Ant Design Button
StatusBadge → Tag, Badge
AuthCard → Card, Form, Input, Alert
ThemePicker → Segmented, Select, ColorPicker
BrandMark와 제품 아이콘 → Ant Design Space, Typography, icon facade

완료 기준

기존 public export가 유지된다.
disabled, loading, danger, size, status 동작이 정의된다.
키보드 및 focus 동작을 테스트한다.
light/dark 및 주요 화면 시각 검증이 완료된다.

Phase 4. 레이아웃 및 네비게이션 전환

PortalShell과 PortalAdminShell을 Ant Design Layout, Sider, Header, Content, Menu, Dropdown, Avatar, Breadcrumb 기반으로 재구성한다. 디렉터리와 권한 정책은 기존 포털 로직을 유지한다.

작업 항목

메뉴 모델을 Ant Design items 형식으로 변환하는 adapter 작성
권한 없는 메뉴를 렌더링 전에 제거
railCollapsed와 onRailCollapsedChange controlled API 유지
반응형 breakpoint 및 mobile drawer 정책 결정
사용자 프로필, 관리자 메뉴, 로그아웃 동작 연결
검색·언어 토글·breadcrumb 영역 표준화
활성 메뉴와 URL 동기화

완료 기준

기존 메뉴 구조와 권한 노출 결과가 동일하다.
접기·펴기, 새로고침, 직접 URL 진입 시 선택 상태가 일관된다.
데스크톱과 모바일 주요 viewport에서 레이아웃이 동작한다.
PortalShell 회귀 테스트가 통과한다.

Phase 5. 데이터 표시·피드백 전환

dataShells, contentComponents, assetAttachments를 Ant Design 데이터 표시 컴포넌트 중심으로 재구성한다.

전환 대상

Table, List, Descriptions
Empty, Result, Skeleton, Spin
Alert, Tag, Tooltip
Upload와 첨부파일 목록 조합

정책으로 유지할 항목

표준 빈 상태 문구
API 오류 변환 규칙
로딩 지연 및 재시도 정책
페이지네이션 기본값
FileStore 권한과 메타데이터 표시
행 선택 및 업무 상태 매핑

완료 기준

loading, empty, error, data 상태가 공통 규칙을 따른다.
표준 테이블의 pagination, sorting, filtering API가 문서화되어 있다.
첨부파일 다운로드·삭제 권한이 유지된다.

Phase 6. Form 및 업무 화면 전환

DirectoryManagement와 PortalThemePolicySettings를 Ant Design Form, Form.Item, Drawer, Modal, Radio, Select, ColorPicker, Descriptions 기반으로 전환한다.

작업 항목

field name과 validation rule 표준화
서버 오류를 field error로 변환하는 adapter 작성
create/edit 화면의 초기값과 reset 동작 정의
dirty state와 navigation blocking 정책 검토
Drawer·Modal 제출 및 취소 동작 통일
접근성 label, help, extra, status 표시 정리

완료 기준

필수값·형식·서버 검증 오류가 동일한 방식으로 표시된다.
제출 중 중복 제출이 차단된다.
실패 시 입력값이 보존되고 재시도가 가능하다.
디렉터리 및 테마 정책 테스트가 통과한다.

Phase 7. 공개 API 및 문서 정리

내부 구현이 안정화되면 공개 API를 역할별로 정리한다. 기존 import 경로는 deprecation 기간 동안 유지한다.

작업 항목

component-level index.ts 추가
루트 src/index.ts export 정리
antd를 peer dependency로 노출할지 bundle dependency로 포함할지 결정
사용하지 않는 legacy CSS와 컴포넌트 제거
README에 Provider 설치와 테마 적용 예시 추가
컴포넌트별 prop, 상태, 접근성, migration note 작성
breaking change가 필요한 항목은 별도 major release로 분리

완료 기준

공개 export 목록이 자동 검증된다.
신규 사용법과 기존 사용법이 문서화되어 있다.
소비 포털의 import 수정 범위가 확정되어 있다.

Phase 8. 통합 검증 및 릴리스

세 포털을 실제 소비자로 연결해 통합 검증한다. ui-react 단독 테스트만으로 완료 처리하지 않는다.

검증 항목

전체 workspace typecheck
전체 unit 및 integration test
light/dark 테마 시각 회귀
주요 viewport 반응형 검증
키보드 탐색 및 focus ring 검증
주요 화면의 bundle size 비교
Ant Design CSS와 포털 CSS 충돌 확인
패키지 publish 및 신규 포털 설치 검증
이전 버전에서의 migration smoke test

완료 기준

세 포털의 핵심 사용자 흐름이 통과한다.
공개 API 변경과 migration 절차가 릴리스 노트에 기록된다.
rollback 가능한 버전과 배포 절차가 준비되어 있다.

7. 컴포넌트 전환 우선순위

우선순위	대상	이유
1	`PortalConfigProvider`	모든 컴포넌트 전환의 기반
2	`PortalButton`, `StatusBadge`	영향 범위가 넓고 구현 난이도가 낮음
3	`AuthCard`, `ThemePicker`	Form·테마 정책 검증에 적합
4	`PortalShell`, `PortalAdminShell`	핵심이지만 회귀 범위가 큼
5	`dataShells`, `contentComponents`	상태 조합과 데이터 정책 정리 필요
6	`assetAttachments`	FileStore 계약과 권한 검증 필요
7	`DirectoryManagement`	테이블·폼·서버 오류 통합이 필요
8	`PortalThemePolicySettings`	테마 Provider 안정화 이후 전환

8. 테스트 전략

단위 테스트

토큰 매핑, 메뉴 adapter, 상태 매핑, 서버 오류 변환, controlled/uncontrolled 동작을 테스트한다.

컴포넌트 테스트

각 컴포넌트의 loading, disabled, empty, error, keyboard, focus, callback 동작을 검증한다.

통합 테스트

PortalConfigProvider 아래에서 테마, locale, message, notification, modal이 함께 동작하는지 확인한다. 셸과 권한 메뉴, 디렉터리 데이터, FileStore 첨부파일을 실제 adapter와 연결해 검증한다.

시각 회귀 테스트

light/dark, collapsed/expanded, empty/loading/error, desktop/mobile 상태를 기준 화면과 비교한다. Ant Design 기본 스타일 변경으로 인한 회귀를 별도로 추적한다.

9. 주요 위험과 대응

위험	대응
Ant Design 기본 스타일이 기존 포털 화면을 크게 변경	토큰 매핑과 단계별 시각 회귀, 컴포넌트별 전환
공개 API가 Ant Design prop에 과도하게 종속	포털 의미를 가진 prop을 우선하고 adapter에서 변환
bundle size 증가	ESM, 개별 icon import, 사용량 측정, 필요 시 package entry 분리
Form validation 동작 차이	기존 validation 사례를 fixture로 만들고 adapter 테스트
메뉴 권한 노출 회귀	render 전 권한 필터와 기존 결과 비교 테스트
Ant Design major 업그레이드 영향	facade와 Provider에 버전 경계를 집중하고 upgrade checklist 운영
기존 CSS와 reset 충돌	CSS layer·import 순서·selector scope를 명시
포털별 예외가 공통 API를 오염	escape hatch를 제한적으로 제공하고 도메인 컴포넌트로 격리

10. 완료 정의

전면 도입은 antd를 설치하는 것으로 완료되지 않는다. 다음 조건을 모두 만족해야 한다.

ui-react의 범용 UI 기본 구현이 Ant Design 기반이다.
포털 전용 정책은 portal-foundation에 중앙화되어 있다.
design-tokens가 테마의 원본으로 유지된다.
모든 공통 컴포넌트가 PortalConfigProvider 아래에서 일관되게 동작한다.
기존 공개 API 또는 명시된 migration이 제공된다.
세 포털의 핵심 사용자 흐름과 light/dark 화면이 검증된다.
테스트, 번들 크기, 접근성, 문서가 릴리스 기준을 충족한다.
문제가 발생했을 때 이전 패키지 버전으로 되돌릴 수 있다.

11. 첫 번째 구현 단위

첫 번째 PR은 다음 범위로 제한한다.

packages/ui-react/package.json에 antd와 @ant-design/icons 추가
PortalConfigProvider 및 Ant Design 토큰 매핑 함수 추가
design-tokens의 light/dark 토큰을 Provider에서 주입
기존 PortalButton을 Ant Design Button 기반으로 교체
Provider와 Button의 단위·컴포넌트 테스트 추가
기존 src/index.tsx export와 사용 예시 유지
빌드·타입 검사·테스트·간단한 시각 검증 수행

첫 번째 PR에서 PortalShell 전체를 교체하지 않는다. Provider와 토큰 계층이 안정된 다음 레이아웃 전환을 별도 PR로 진행한다.

assets

common-ui-template-guide

Ant Design 전면 도입 작업계획

1. 문서 목적

2. 최종 방향

3. 적용 범위

4. 지켜야 할 설계 원칙

4.1 디자인 토큰의 소유권

4.2 공개 API 안정성

4.3 도메인 정책의 중앙화

4.4 controlled/uncontrolled 규칙

4.5 단계별 교체

5. 권장 디렉터리 구조

6. 단계별 실행 순서

Phase 0. 기준선 확보

Phase 1. 의존성 및 스타일 기반 정리

Phase 2. 토큰 매핑과 `PortalConfigProvider` 구축

Phase 3. 기반 컴포넌트 전환

Phase 4. 레이아웃 및 네비게이션 전환

Phase 5. 데이터 표시·피드백 전환

Phase 6. Form 및 업무 화면 전환

Phase 7. 공개 API 및 문서 정리

Phase 8. 통합 검증 및 릴리스

7. 컴포넌트 전환 우선순위

8. 테스트 전략

단위 테스트

컴포넌트 테스트

통합 테스트

시각 회귀 테스트

9. 주요 위험과 대응

10. 완료 정의

11. 첫 번째 구현 단위

12. 참고 문서

Ant Design 전면 도입 작업계획 ​

1. 문서 목적 ​

2. 최종 방향 ​

3. 적용 범위 ​

4. 지켜야 할 설계 원칙 ​

4.1 디자인 토큰의 소유권 ​

4.2 공개 API 안정성 ​

4.3 도메인 정책의 중앙화 ​

4.4 controlled/uncontrolled 규칙 ​

4.5 단계별 교체 ​

5. 권장 디렉터리 구조 ​

6. 단계별 실행 순서 ​

Phase 0. 기준선 확보 ​

Phase 1. 의존성 및 스타일 기반 정리 ​

Phase 2. 토큰 매핑과 PortalConfigProvider 구축 ​

Phase 3. 기반 컴포넌트 전환 ​

Phase 4. 레이아웃 및 네비게이션 전환 ​

Phase 5. 데이터 표시·피드백 전환 ​

Phase 6. Form 및 업무 화면 전환 ​

Phase 7. 공개 API 및 문서 정리 ​

Phase 8. 통합 검증 및 릴리스 ​

7. 컴포넌트 전환 우선순위 ​

8. 테스트 전략 ​

단위 테스트 ​

컴포넌트 테스트 ​

통합 테스트 ​

시각 회귀 테스트 ​

9. 주요 위험과 대응 ​

10. 완료 정의 ​

11. 첫 번째 구현 단위 ​

12. 참고 문서 ​

Ant Design 전면 도입 작업계획

1. 문서 목적

2. 최종 방향

3. 적용 범위

4. 지켜야 할 설계 원칙

4.1 디자인 토큰의 소유권

4.2 공개 API 안정성

4.3 도메인 정책의 중앙화

4.4 controlled/uncontrolled 규칙

4.5 단계별 교체

5. 권장 디렉터리 구조

6. 단계별 실행 순서

Phase 0. 기준선 확보

Phase 1. 의존성 및 스타일 기반 정리

Phase 2. 토큰 매핑과 `PortalConfigProvider` 구축

Phase 3. 기반 컴포넌트 전환

Phase 4. 레이아웃 및 네비게이션 전환

Phase 5. 데이터 표시·피드백 전환

Phase 6. Form 및 업무 화면 전환

Phase 7. 공개 API 및 문서 정리

Phase 8. 통합 검증 및 릴리스

7. 컴포넌트 전환 우선순위

8. 테스트 전략

단위 테스트

컴포넌트 테스트

통합 테스트

시각 회귀 테스트

9. 주요 위험과 대응

10. 완료 정의

11. 첫 번째 구현 단위

12. 참고 문서