Ant Design to shadcn/ui Migration Guide

Comprehensive guide for migrating legacy Ant Design frontends to shadcn/ui + Tailwind (Radix under the hood), covering component equivalence, theming/tokens, layout/navigation, forms/tables, overlays/alerts, accessibility, and bundle-size cleanup. Targets React (CRA/Vite) apps moving to Next.js App Router, with patterns for running Ant and shadcn side-by-side during transition. Includes automated skeleton generation guidance for fresh layouts/pages with role-aware routing.

When to Apply

• Migrating a CRA/Vite React app that uses Ant Design to Next.js App Router with shadcn/ui.
• Replacing Ant Design components with shadcn/ui (and Radix) while moving styling to Tailwind and design tokens.
• Cleaning up legacy global CSS/LESS, z-index stacks, and inline styles that conflict with Tailwind/shadcn.
• Generating fresh layout/page skeletons per route (optionally role-aware) to reduce legacy cruft.

Version Policy

Use the latest stable versions of:

• next ≥ 16.x (App Router)
• react ≥ 19.x
• tailwindcss ≥ 3.4.x
• shadcn/ui latest
• @radix-ui packages as pulled by shadcn/ui
• class-variance-authority, tailwind-merge, lucide-react, sonner
• react-hook-form ≥ 7.x and zod ≥ 3.x for forms (recommended)

Rule Categories by Priority

Component Equivalence (Matrix)

Notes on gaps

• Rate: star toggles via Button/Toggle.
• Transfer: dual list with checkboxes and CTA buttons.
• QRCode: use a QR library; render inside Card.
• Tour: custom step popovers anchored to elements.
• Watermark: CSS background-image or canvas; keep scoped.
• Affix: position: sticky on containers.
• Tree: indented list; add virtualization for large sets.
• Pro* suites: rebuild via tanstack table + forms + cards; no direct shadcn equivalent.
• ConfigProvider/App/Util: not needed; use Tailwind/shadcn tokens and providers already configured.
• Masonry: CSS columns or grid with grid-auto-rows + spans.
• Statistic: simple text/number in Card with muted labels.
• Shadcn-only (helpful replacements): Command/Combobox for search/select; Sonner for toasts; Menubar/Sidebar for complex nav; Spinner for lightweight loading; Chart (community/blocks) where Ant charts were used; Input OTP for code entry; Field/Textarea for richer forms.

Migration Order

0. Verify/upgrade Ant to latest 6.x before mapping (align with Ant components).
1. Setup: Tailwind/shadcn install, deps, project structure, shadcn MCP server ready.
2. CSS Cleanup: Identify global/LESS/inlined styles; decide what to keep; add base resets and z-index tokens.
3. Theming: Map Ant tokens → CSS vars/Tailwind theme; dark mode guardrails; spacing/radius/typography scales.
4. Layout/Nav (Responsive): Rebuild layouts/nav/breadcrumbs with desktop/tablet/mobile variants; role-aware scaffolding; drawer-on-mobile.
5. Forms: Convert Form.Item patterns to shadcn + react-hook-form + zod; validation and submission states; success/failure/inline errors.
6. Data Display: Tables/lists/empty states; pagination/sorting/filtering patterns; loading/skeleton/error states.
7. Overlays/Feedback: Dialogs/sheets/popovers/tooltips/toasts/alerts/spinners with z-index scale.
8. Content/Icons: Replace Ant icons/typography with lucide and Tailwind text styles; see content-icons-typography.
9. Accessibility/Interop: Focus traps, keyboard nav, ARIA, responsive checks; safe coexistence during phased rollout; see a11y-responsive-checks, a11y-motion-contrast, responsive-touch, rtl-l10n.
10. Testing/Verification: Visual checks, a11y scans, bundle/size linting, API/error-path checks; prefer modern UX fallbacks over 1:1 Ant copies when overlays/patterns conflict (gotchas-ux-fallbacks).
11. Performance/Bundle: verify Ant CSS/icons absent; use lucide; virtualize large tables/lists to avoid jank (perf-bundle-guard).
12. Observability: keep analytics/error logging when refactoring flows; don’t drop events when swapping notifications with toasts (analytics-observability).
13. Scroll/State: guard useEffect/init to avoid state resets; use stable handlers and shadcn ScrollArea for section navigation (gotchas-scroll-state).

Scans and Mapping

Run scans to route findings to rules:

• antd imports and package version → setup-antd-upgrade, setup-, css-legacy, theme-bridge, component mappings.
• ConfigProvider, theme.useToken → theme-bridge, theme-dark-mode, css-layering.
• Global CSS/LESS (*.less, global.css, index.css) → css-legacy-inventory, css-layering, css-asset-hygiene.
• Inline style= with Ant tokens → theme-bridge, css-inline-cleanup.
• Duplicate/placeholder components/pages (NewButton, NewPage, *V2) → gotchas-component-sprawl.
• Layout.Sider, Menu, Breadcrumb → layout-shell, layout-nav.
• Form, Form.Item, message, notification, Modal.confirm → forms-*, overlay-*, gotchas-ux-fallbacks.
• Table, List, Descriptions, Tag, Badge, Empty → data-*, components-* (pagination/result/empty), data-table-tanstack.
• Route configs/menus/guards → layout-route-scaffold, layout-auth-discovery, gotchas-coexistence.
• Auth/roles (Clerk/Supabase/cookies/hooks), router guards, landing vs app shell → layout-auth-discovery.
• @ant-design/icons, global Ant CSS, LESS files → content-icons-typography, css-legacy-inventory, perf-bundle-guard.
• Dark-mode selectors or toggles → theme-dark-mode-guardrails.
• Public assets references → css-asset-hygiene, assets-images.
• Fonts → fonts-setup.
• Scroll/section nav code → gotchas-scroll-state.
• Reduced motion/contrast/focus → a11y-motion-contrast, a11y-responsive-checks, responsive-touch.
• RTL/l10n → rtl-l10n.
• Analytics/logging → analytics-observability.

Quick scan commands (adjust paths as needed)

# Ant version
npm ls antd

# Ant imports and icons
rg \"antd\" src app
rg \"@ant-design/icons\" src app

# ConfigProvider and tokens
rg \"ConfigProvider\" src app
rg \"theme\\.useToken\" src app

# Ant imperative APIs
rg \"Modal\\.confirm\" src app
rg \"notification\\.\" src app
rg \"message\\.\" src app

# Table/columns
rg \"columns\\s*=\\s*\\[\" src app

# LESS and global CSS
rg --files -g\"*.less\" src app
rg \"global\\.css\" src app

# Dark mode selectors
rg \"\\.dark\" src app

# Assets and fonts
rg --files -g\"*.{png,jpg,jpeg,svg}\" public/ src app
rg \"font-family\" src app

# Responsive/touch/scroll
rg \"overflow\" src app
rg \"scrollIntoView\" src app

# Routes/guards/menus
rg \"<Router\" -g\"*.tsx\" src app
rg \"RequireAuth|useAuth|Clerk|Supabase\" src app
rg \"menu\" src app/components

# Analytics/logging
rg \"track|analytics|logEvent\" src app

Post-Migration Verification (UI-first)

• Shell/nav: responsive desktop/tablet/mobile; active states; breadcrumbs; role-guarded routes.
• Forms: validation + error/success toasts; disabled states; loading indicators; keyboard focus order; screen reader labels.
• Tables/lists: empty/loading/error/skeleton states; pagination/sort/filter; row focus/hover.
• Overlays/toasts: focus trap, ESC/close, return focus; z-index layering; no console errors on open/close.
• Theming: light/dark parity; token application (colors/spacing/radius); contrast and focus outlines.
• CSS sanity: no leaking global styles; no unexpected z-index overlaps; Ant CSS isolated or removed; legacy UI parked separately.
• Performance: bundle size reduced (no Ant CSS), tree-shaking verified.

Rule Index (by prefix)

• Setup: setup-antd-upgrade, setup-shadcn-install, setup-shadcn-mcp, setup-legacy-parking, build-env
• Theme: theme-bridge-tokens, theme-dark-mode-guardrails
• Layout: layout-route-scaffold, layout-responsive-shell, layout-auth-discovery
• Forms: forms-rhf-shadcn, forms-api-states, forms-select-date-upload
• Data: data-tables-state, data-table-tanstack, components-pagination, components-result-empty
• Overlays: overlay-alerts-toasts, overlay-toast-console
• Components (augment data/overlay): components-tabs-steps, components-tree-cascader, components-upload, components-pagination, components-result-empty
• Content: content-icons-typography
• Styling: css-legacy-inventory, css-asset-hygiene, assets-images, fonts-setup
• Accessibility/Responsive: a11y-responsive-checks, a11y-motion-contrast, responsive-touch, rtl-l10n
• Performance: perf-bundle-guard
• Testing: test-visual-a11y, test-e2e-visual
• Gotchas: gotchas-coexistence, gotchas-ux-fallbacks, gotchas-scroll-state, gotchas-component-sprawl
• Other: analytics-observability

How to Use

1. Run scans to inventory Ant usage, CSS/LESS, routes/roles, and inline styles.
2. Apply rules by category (see rules/), starting with setup, CSS cleanup, theming, then layout/forms/data/overlays.
3. Enforce component singularity: replace Ant components (no wrappers), squash custom duplicates into canonical shadcn components, and keep styling via variants/classes.
4. Generate new App Router layouts/pages per route with shadcn skeletons; use clean naming, wire routes to nav/tests, and keep Ant only where not yet migrated (side-by-side strategy).
5. Verify with the post-migration checklist; add visual/a11y snapshots where possible.

Structure readiness check (reuse vs fresh scaffold)

• Reuse existing structure if: routes/nav/breadcrumb data are centralized; CSS/LESS is scoped/minimal; assets/fonts are organized; guards/roles are discoverable and centralized.
• Fresh scaffold if: routing/layouts are unclear, Ant CSS bleeds globally, assets/styles are scattered, or guards/roles are ad-hoc.
• Always run scans first (antd imports, ConfigProvider, LESS, icons, overflow/scroll, assets/fonts, routes/guards, analytics) to inform the choice.

Component sourcing (shadcn-first)

• Install components via shadcn CLI/MCP (registry) only; do not hand-roll replacements if a shadcn component/block exists.
• Prefer shadcn MCP for updated patterns/blocks; avoid custom ad-hoc builds unless the component does not exist in the registry.
• Keep installs tracked in components.json and use npx shadcn@latest for additions.