Phase 5 Ant Design 마이그레이션 결정사항

List와 Listy

Ant Design 6.6부터 List는 다음 major에서 제거 예정이라는 warning을 출력한다. 기존 dataSource, renderItem, rowKey, List.Item, List.Item.Meta public markup 계약을 유지하기 위해 packages/ui-react/src/components/PortalList.tsx에 호환 adapter를 추가하고 내부 primitive를 Listy로 전환했다.

PortalList는 기존 Portal Foundation consumer가 사용하던 dataSource와 renderItem 형태를 유지하고, ant-list, ant-list-item, ant-list-item-meta class 및 PortalList.Item.Meta 구조를 제공한다. 현재 사용처는 PortalExploreDialog, menuManagement, assetAttachments다. 테스트에서 Ant Design List deprecation warning이 더 이상 발생하지 않으며, 기존 callback·접근성·wrapper class 계약은 유지된다.

Listy는 virtual list에 최적화된 primitive이므로 향후 대규모 데이터 목록에서는 height, itemHeight, virtual rendering을 별도 도입할 수 있다. 현재 adapter는 기존 목록의 정적·유동 높이 markup 호환성을 우선한다.

Modal과 SSR

Ant Design Modal은 SSR에서 portal을 열려고 할 때 client-only portal warning을 출력할 수 있다. PortalDialog와 PortalExploreDialog는 getContainer={false}를 사용하고, useEffect로 client mount가 완료된 뒤에만 Modal open을 true로 전달한다. 따라서 서버 정적 렌더링에는 wrapper만 생성되고 portal은 생성되지 않으며, client mount 후 기존 open 상태로 상호작용할 수 있다.

Modal open/close, ESC, focus return은 PortalExploreDialog browser-level test와 소비 포털의 browser test에서 확인해야 한다. 이번 변경으로 workspace SSR contract test 및 browser-level test에서 기존 portal warning이 발생하지 않는 것을 확인했다.

CSS와 token

Ant Design primitive의 색상·크기·상태는 PortalConfigProvider와 component token을 우선한다. packages/ui-react/styles/styles.css에는 pf-* wrapper, 레이아웃, 반응형 동작, 기존 공개 class contract만 남긴다. Ant Design DOM class에 직접 결합하거나 native control을 중복 스타일링하는 규칙은 후속 CSS audit에서 제거한다. focus-visible ring을 덮어쓰는 selector와 light/dark 대비를 함께 점검한다.

Feature 디렉터리와 compatibility export

도메인 구현은 다음 feature 디렉터리로 분리되어 있으며 root index.tsx는 기존 public API를 위한 compatibility facade로 유지된다.

• src/admin: PortalAdminShell, DirectoryManagement
• src/auth: AuthCard
• src/branding: BrandMark
• src/explore: PortalExploreDialog 및 browser-level test
• src/navigation: menu management와 access adapter
• src/theme: PortalThemePolicySettings

이번 작업에서 확인된 잔여 항목

• 소비 포털 smoke test 및 light/dark 시각 회귀
• 다음 major에서 PortalList의 virtual list 옵션 도입 검토
• 전체 CSS selector 및 token 대비 audit

메뉴 access rule adapter, PortalThemePolicySettings Form 계약, 관리자 동기화 상태·오류 semantics, admin/theme feature 분리, Listy 전환, SSR Modal warning 대응은 완료했다.