antd-style → Tailwind CSS Migration

When to apply

• User asks to migrate / rewrite / convert a component's styles to Tailwind
• A new feature is being built in a file that currently uses createStyles
• User references styles.ts, createStyle, useXxxStyles, or cx()
• Component contains antd Button — replace with shadcn Button during migration

Prerequisites

Always read these files before starting:

• The target component (index.tsx or equivalent)
• Its styles.ts
• tailwind.config.js and src/index.css if token mapping is unclear

Migration Steps

1. Audit the styles.ts

Identify:

• Styles used only by this component → remove from styles.ts
• Styles shared with other components → keep createStyles for those

Also check if the styles file is imported anywhere else before deleting:

rg "from.*ComponentName/styles" --type tsx --type ts

2. Replace createStyles wiring

- import { useXxxStyles } from "./styles"
+ import { cn } from "@/opensource/lib/utils"

  const targetComponent = observer((props) => {
-   const { styles, cx } = useXxxStyles()

Use cn() everywhere cx() was used.

Do not build class strings with + concatenation. Prefer:

const segmentedClassName = cn(
	"rounded-md border border-border p-1",
	"[&_.magic-segmented-group]:gap-0.5",
	"[&_.magic-segmented-item-label]:text-xs",
)

3. Z-index semantic tokens

Prefer semantic z-index classes over arbitrary z-[N] values.

Choose by context: use z-tooltip for tooltips, z-dropdown for menus, z-dialog for modals.

4. Translate CSS properties

5. Map design tokens

Prefer semantic Tailwind vars — they auto-adapt to dark mode.

Project-specific opacity tokens (from src/index.css):

• Primary light token keeps semantic suffix (bg-primary-10) due mixed light/dark opacity mapping
• Destructive opacity should use slash syntax (bg-destructive/10, bg-destructive/20)

6. Map hardcoded hex colors

7. Pseudo-elements

::after / ::before with decorative content:

// Before (antd-style)
wrapper: css`
	position: relative;
	&::after {
		content: " ";
		position: absolute;
		left: 11px;
		top: 0;
		width: 1px;
		height: 100%;
		border-left: 1px dashed ${token.magicColorScales.grey[2]};
	}
`

// After (Tailwind)
;("relative after:content-[''] after:absolute after:left-[11px] after:top-0 after:w-px after:h-full after:border-l after:border-dashed after:border-border")

8. Child selectors

9. CSS animations

10. Replace antd layout components

antd layout primitives (Flex, Space, Row, Col) must be replaced with plain <div> + Tailwind.

Flex → div

- import { Flex } from "antd"

- <Flex vertical gap={10}>
-   <span>…</span>
-   <Flex gap={8}>…</Flex>
- </Flex>

+ <div className="flex flex-col gap-2.5">
+   <span>…</span>
+   <div className="flex gap-2">…</div>
+ </div>

Space → div

- <Space size={8} direction="vertical">
+ <div className="flex flex-col gap-2">

10.5 Replace MagicScrollBar with shadcn ScrollArea

When migrating legacy list areas:

- import MagicScrollBar from "@/opensource/components/base/MagicScrollBar"
+ import { ScrollArea } from "@/opensource/components/shadcn-ui/scroll-area"

Map old SimpleBar content padding to viewportClassName:

- <MagicScrollBar className="h-full w-full [&_.simplebar-content]:px-2.5 [&_.simplebar-content]:pb-2.5">
+ <ScrollArea className="min-h-0 h-full w-full" viewportClassName="px-2.5 pb-2.5">

Critical height-chain rule (flex layouts):

• Every ancestor from panel body to ScrollArea must provide a calculable height
• Typical safe chain: flex-1 min-h-0 overflow-hidden on parent + min-h-0 h-full on ScrollArea
• Avoid wrapping ScrollArea with components that add an extra auto-height layer (for example spinner wrappers) unless that wrapper and its direct child are both h-full

If loading overlay breaks scrolling, prefer rendering loading as a branch:

{
	loading ? (
		<div className="flex h-full w-full items-center justify-center">{/* spinner */}</div>
	) : (
		<ScrollArea className="min-h-0 h-full w-full" viewportClassName="px-2.5 pb-2.5">
			{/* list */}
		</ScrollArea>
	)
}

Keep existing data-testid values on list / loading / empty nodes when replacing containers.

11. Replace antd Button with shadcn Button

When migrating a component that uses antd Button, replace it with shadcn Button from @/opensource/components/shadcn-ui.

Import change

- import { Button } from "antd"
+ import { Button } from "@/opensource/components/shadcn-ui"

antd → shadcn mapping

Example migration

- import { Button } from "antd"
- import { IconDownload } from "@tabler/icons-react"
+ import { Button } from "@/opensource/components/shadcn-ui"
+ import { IconDownload } from "@tabler/icons-react"  // or lucide-react

- <Button type="primary" icon={<IconDownload size={20} />} onClick={handleDownload}>
-   {t("detail.downloadFile")}
- </Button>
+ <Button onClick={handleDownload} size="sm">
+   <IconDownload className="size-5" />
+   {t("detail.downloadFile")}
+ </Button>

shadcn Button has built-in [&_svg]:size-4; use className="size-5" on the icon for 20px. Remove any className overrides that were needed for antd — shadcn Button uses Tailwind and supports className for minor tweaks only.

11.5 Replace antd Input with shadcn Input

When migrating a component that uses antd Input, replace it with shadcn Input from @/opensource/components/shadcn-ui/input.

Import change

- import { Input } from "antd"
+ import { Input } from "@/opensource/components/shadcn-ui/input"

Prefix icon migration

Antd prefix prop is not used in shadcn Input. Wrap Input with a relative container and render the icon absolutely:

<div className="relative w-full">
	<IconSearch
		size={16}
		className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground"
	/>
	<Input
		value={searchText}
		onChange={(event) => setSearchText(event.target.value)}
		className="pl-9"
		placeholder={t("mcp.panel.searchPlaceholder")}
	/>
</div>

Notes

• Keep data-testid unchanged during migration
• Preserve placeholder and controlled value logic
• Use fixed width wrapper only when desktop layout needs it (for example w-[240px])

12. Antd component overrides (non-Button)

When applying Tailwind to other antd components (Dropdown, Modal, etc.), antd's CSS specificity requires !important for most visual properties. Layout utilities like flex-none do NOT need ! since they're additive.

Workspace rule (critical): for internal antd class overrides, use .magic-* prefix, not .ant-*.

• ✅ "[&_.magic-alert]:text-xs"
• ❌ "[&_.ant-alert]:text-xs"

// Dropdown overlayClassName targeting internal antd classes
overlayClassName="[&_.magic-dropdown-menu]:!p-[6px] [&_.magic-dropdown-menu]:flex
  [&_.magic-dropdown-menu]:flex-col [&_.magic-dropdown-menu]:gap-1
  [&_.magic-dropdown-menu-item]:!p-0"

Rule of thumb for !: Does antd set this property by default? If yes → !. If it's purely additive (flex-none, mt-2.5, self-end) → no ! needed.

13. Interactive states (hover / active / focus / disabled)

Always add all four states when styling interactive elements. Missing any state causes visible regressions (e.g., a button that darkens on hover but ignores keyboard focus).

State token mapping

Ghost button (bg-background + border)

// Canonical ghost button pattern — always use cn()
const ghostButton = cn(
	"inline-flex items-center cursor-pointer rounded-lg",
	"bg-background text-foreground border border-border",
	"hover:bg-fill hover:text-foreground",
	"active:bg-fill-secondary",
	"focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
	"disabled:pointer-events-none disabled:opacity-50",
)

Filled button (bg-primary)

const primaryButton = cn(
	"bg-primary text-primary-foreground",
	"hover:bg-primary/90",
	"active:bg-primary/80",
	"focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
	"disabled:pointer-events-none disabled:opacity-50",
)

Filled muted button (bg-muted / bg-fill)

const mutedButton = cn(
	"bg-fill text-foreground",
	"hover:bg-fill-secondary hover:text-foreground",
	"active:bg-black/[0.13] dark:active:bg-white/[0.13]",
	"focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
	"disabled:pointer-events-none disabled:opacity-50",
)

Shared const pattern (for custom div buttons)

When building custom button-like elements (not shadcn Button), extract to a module-level const:

// Outside component — for div/span that acts as button
const actionButtonBase = cn(
  "inline-flex h-6 items-center gap-1 px-2.5 py-1",
  "cursor-pointer rounded-lg text-xs leading-4",
  "bg-background text-foreground border border-border",
  "hover:bg-fill hover:text-foreground",
  "active:bg-fill-secondary",
  "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
  "disabled:pointer-events-none disabled:opacity-50",
)

// For shadcn Button — use variant/size props, className for minor tweaks only
<Button variant={isActive ? "default" : "outline"} size="sm">

Dark Mode Patterns

Add dark: variants for all hardcoded light-specific colors.

Semantic Tailwind variables (bg-background, border-border, text-foreground, bg-muted, bg-fill, bg-fill-secondary) are already dark-mode aware — no dark: prefix needed.

Dark Mode Verification Checklist

After migration, verify dark mode styles are complete:

1. Scan for hardcoded light colors without dark:

   • bg-white, bg-gray-50, bg-orange-50, bg-green-50, bg-blue-50, bg-amber-50
   • text-gray-400, text-gray-500, text-orange-500, text-green-500, text-blue-500
   • bg-[#...], text-[#...] (hex values)
   • border-gray-200, border-gray-300
   • Each of these must have a matching dark: variant.

2. Verify semantic tokens

   • Prefer bg-background, text-foreground, border-border, bg-muted, bg-fill — these auto-adapt.
   • If using fixed colors (e.g. bg-white), always pair with dark:bg-card or equivalent.

3. Interactive elements

   • hover:, active: states using light-only colors need dark: variants.
   • Example: hover:bg-gray-100 → add dark:hover:bg-white/10.

4. Manual verification

   • Toggle dark mode in the app and visually inspect the migrated component.
   • Check: backgrounds, text contrast, borders, shadows, focus rings.
   • Ensure no "invisible" text or low-contrast elements in dark mode.

5. Search pattern for audit

   # Find light-only color classes — verify each has a dark: variant in same className
   rg "bg-(white|gray-50|orange-50|green-50|blue-50|amber-50)" --type tsx path/to/component
   rg "text-(gray-[34]00|orange-500|green-500|blue-500)" --type tsx path/to/component

React patterns to fix during migration

Prefer proper types over eslint-disable / as any

When passing props to child components, fix type errors by using proper interfaces instead of as any or eslint-disable-next-line @typescript-eslint/no-explicit-any.

1. Export the child's props interface from the child component:

   - interface PlaybackTabContentProps {
   + export interface PlaybackTabContentProps {

2. Use that interface as the parent's prop type:

   - playbackProps?: Record<string, unknown>
   + playbackProps?: PlaybackTabContentProps

3. Remove type assertions — spread directly without as any:

   - <PlaybackTabContent {...(playbackProps as any)} />
   + <PlaybackTabContent {...playbackProps} />

4. Simplify property access — no cast needed:

   - (playbackProps as Record<string, unknown>)?.isFullscreen === true
   + playbackProps?.isFullscreen === true

Reserve eslint-disable only for cases where proper typing is impractical (e.g. MobX store data with loose typing in .map() callbacks). Prefer exporting interfaces and typing props correctly.

Object initializer in deps causes stale closure warnings

The pattern const x = thing || {} creates a new object reference every render, causing ESLint to warn about unstable useCallback/useMemo deps. Wrap it in useMemo:

- const fileData = tool?.detail?.data || {}
+ const fileData = useMemo(() => tool?.detail?.data || {}, [tool?.detail?.data])

@ts-ignore vs @ts-expect-error

• @ts-ignore — suppresses the error silently; ESLint bans it.
• @ts-expect-error — requires a real error to exist; errors if the line is clean.

Migration rule:

1. Replace // @ts-ignore with // @ts-expect-error and add a brief reason.
2. Run lint. If you get "Unused '@ts-expect-error' directive" → the line is already clean, just delete the comment entirely.

- // @ts-ignore
+ // @ts-expect-error - result type does not expose data.file_id
  const fileId = result?.data?.file_id || result?.currentFileId

any on JSX .map() callbacks over store data (last resort)

When iterating over data from a MobX/Zustand store with loose typing, first try to add proper types (e.g. define StoreItem interface, use as StoreItem where the parent builds the data). Use eslint-disable only when proper typing is impractical (e.g. store shape is dynamic or external).

{
	/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
}
{
	items?.map((item: any) => (
		<Child data={item.attrs as ExpectedType} key={getUniqueId(item.attrs as ExpectedType)} />
	))
}

⚠️ The eslint-disable-next-line comment must be on the line immediately before the {items?.map( expression — not before the wrapping {condition && ( wrapper.

Shared base class pattern

When multiple elements share the same base styles, extract into a const outside the component:

// Before (in createStyles)
box: css`border-radius: 12px; display: inline-flex; padding: 4px 8px; ...`

// After (module-level const)
const boxBase = "rounded-[12px] inline-flex px-2 py-1 items-center text-xs gap-1 [&_p]:mb-0"

// Usage
<span className={cn(boxBase, "bg-amber-50 text-amber-500 dark:bg-amber-500/10 dark:text-amber-400")}>

Checklist before finishing

• All styles.xxx references replaced with Tailwind classes
• useXxxStyles import and call removed from component
• createStyles export removed from styles.ts (if no other consumers)
• keyframes import removed from styles.ts if unused
• styles.ts file deleted after confirming no other imports
• cn() imported from @/opensource/lib/utils
• No className + concatenation; use cn(...) instead
• antd Button replaced with shadcn Button from @/opensource/components/shadcn-ui
• antd Input replaced with shadcn Input from @/opensource/components/shadcn-ui/input
• If MagicScrollBar was replaced, ScrollArea uses viewportClassName and height-chain (min-h-0 + h/full) is verified
• Dark mode verification: All hardcoded light colors have dark: variants; prefer semantic tokens (bg-background, text-foreground, etc.); manually verify in dark mode
• antd layout components (Flex, Space, Row, Col) replaced with div + Tailwind
• Unused antd imports removed after replacement
• Interactive elements have all four states: hover: / active: / focus-visible: / disabled:
• Repeated button/link classes extracted to a module-level const (DRY)
• token.borderRadiusSM translated to rounded-[4px], not rounded-sm
• Object initializers used as hook deps wrapped in useMemo
• @ts-ignore replaced with @ts-expect-error + reason, or deleted if no error exists
• Type safety: Props passed to children use proper interfaces (export from child, use in parent); avoid as any and eslint-disable for type errors
• any in JSX map callbacks used only as last resort; prefer proper types when feasible
• ! prefix on antd overrides applied correctly (visual props only, not layout utilities)
• Antd override selectors use .magic-* class prefix, not .ant-*
• Lints pass (pnpm lint)

Additional resources

• Color mapping details: color-mapping.md