Ant Design Patterns

Quick Guide: Ant Design is an enterprise-grade React UI library providing a complete set of high-quality components. Use ConfigProvider with design tokens for theming, the three-layer token system (Seed, Map, Alias) for customization, and the App component for context-aware feedback methods. Current: v6.x (pure CSS variables by default, zero-runtime mode, React 18+ required). v5.x is in maintenance. All patterns in this skill apply to both v5 and v6 unless noted.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST wrap your app with ConfigProvider for theming and locale - never override component styles with global CSS)

(You MUST use the App component and useApp() hook for message/notification/modal - never use static methods directly as they cannot consume ConfigProvider context)

(You MUST use Form.useForm() with TypeScript generics for type-safe form handling - never use untyped form instances)

(You MUST use CSS variables mode (cssVar: true) for optimal theme-switching performance in production)

</critical_requirements>

Auto-detection: Ant Design, antd, ConfigProvider, theme.defaultAlgorithm, theme.darkAlgorithm, theme.compactAlgorithm, useToken, Form.useForm, Form.List, Form.useWatch, ProTable, ProForm, ProLayout, @ant-design/icons, @ant-design/pro-components, AntdRegistry, Table columns, message.success, notification.open, Modal.confirm

When to use:

• Building enterprise admin panels, dashboards, and data-heavy applications
• Need a comprehensive component library with consistent design language out of the box
• Working with complex data tables, forms with validation, and multi-step workflows
• Requiring built-in internationalization, dark mode, and theme customization

When NOT to use:

• Building a custom design system from scratch (use headless primitives)
• Need minimal bundle size for a simple marketing site (Ant Design is large)
• Want full control over styling without design opinions (use unstyled primitives)
• Building non-React applications (Ant Design is React-specific)

Key patterns covered:

• ConfigProvider theming with design tokens (Seed, Map, Alias, Component tokens)
• Table with sorting, filtering, virtual scrolling, and custom rendering
• Form with validation, dynamic fields (Form.List), and TypeScript generics
• Layout system (Layout, Grid, Space, Flex)
• Feedback patterns (Modal, Message, Notification via App/useApp)
• Dark mode and theme switching with algorithms
• Next.js SSR with AntdRegistry
• Pro Components (ProTable, ProForm, ProLayout)

Examples

• Core Setup & Theming -- ConfigProvider, App wrapper, design tokens, dark mode, nested themes, useToken
• Forms & Validation -- Form, Form.Item, validation rules, useForm, Form.List, Form.useWatch, modal form
• Tables -- Table, columns, sorting, filtering, pagination, row selection, virtual scrolling, expandable rows
• Layout -- Layout, Sider, Header, Content, Grid (Row/Col), Space, Flex
• Feedback Components -- Modal, Drawer, message, notification, useApp
• Data Display -- Card, Descriptions, Statistic, Tag, Badge
• Navigation & Icons -- Menu, Breadcrumb, icon tree-shaking, custom icons
• Pro Components -- ProLayout, ProTable, ProForm, StepsForm
• Next.js Integration -- AntdRegistry, SSR, client components, App Router
• Internationalization -- ConfigProvider locale, dayjs locale sync

For quick reference and component checklists, see reference.md.

Philosophy

Ant Design follows the principles of Natural, Certain, Meaningful, and Growing to provide an enterprise-grade design system. It solves UI consistency across large teams by providing:

• Complete component set: 60+ components covering layout, data display, data entry, navigation, and feedback
• Design token system: Three-layer architecture (Seed > Map > Alias) enabling systematic customization without CSS overrides
• Enterprise patterns: Built-in pagination, filtering, form validation, internationalization, and accessibility

Architecture (CSS-in-JS with CSS Variables): Ant Design uses a CSS-in-JS engine (@ant-design/cssinjs) with design tokens. v6 defaults to pure CSS Variables mode for reduced bundle size and instant theme switching. v6 also supports zero-runtime mode (zeroRuntime: true) where styles are pre-extracted to static CSS. Tree-shaking is built-in -- no babel-plugin-import needed.

When to use Ant Design:

• Enterprise admin interfaces with data tables, forms, and dashboards
• Internal tools where development speed matters more than unique design
• Projects needing i18n, RTL, and accessibility out of the box
• Teams wanting a comprehensive, well-documented component library

When NOT to use:

• Consumer-facing products needing distinctive brand design (too opinionated)
• Performance-critical SPAs where bundle size must be minimal
• Projects using a utility-class-first styling paradigm

Core Patterns

Pattern 1: App Root Setup

The minimal app setup wraps everything in ConfigProvider + App:

import { ConfigProvider, App as AntApp } from "antd";
import type { ThemeConfig } from "antd";
import enUS from "antd/locale/en_US";

const THEME_CONFIG: ThemeConfig = {
  cssVar: true,
  token: { colorPrimary: "#1677ff", borderRadius: 6 },
};

function App() {
  return (
    <ConfigProvider theme={THEME_CONFIG} locale={enUS}>
      <AntApp>
        <MainContent />
      </AntApp>
    </ConfigProvider>
  );
}
export { App };

Why this structure: ConfigProvider provides theme tokens and locale to all children. App component enables context-aware message/notification/modal APIs. cssVar mode optimizes theme switching performance.

See examples/core.md for enterprise theme, dark mode toggle, nested themes, and useToken patterns.

Pattern 2: Design Tokens and Theming

Ant Design uses a three-layer token system:

• Seed Tokens: Foundational values (colorPrimary, fontSize, borderRadius) that derive all other tokens
• Map Tokens: Derived from seed tokens via algorithms (colorPrimaryBg, colorPrimaryHover)
• Alias Tokens: Semantic tokens mapping to use cases (colorBgContainer, colorTextHeading)
• Component Tokens: Per-component overrides (Button.primaryShadow, Table.headerBg)

// Access tokens programmatically for custom components
import { theme } from "antd";
const { useToken } = theme;

function CustomCard() {
  const { token } = useToken();
  return (
    <div
      style={{ background: token.colorBgContainer, padding: token.paddingLG }}
    >
      Styled with design tokens
    </div>
  );
}

See examples/core.md for full theme configuration, nested themes, and StatusCard using useToken.

Pattern 3: Dark Mode and Theme Switching

import { ConfigProvider, theme as antTheme } from "antd";

// Switch between algorithms for dark/light/compact modes
const themeConfig = {
  cssVar: true,
  algorithm: isDark ? antTheme.darkAlgorithm : antTheme.defaultAlgorithm,
  token: { colorPrimary: "#1677ff" },
};

// Combine algorithms: dark + compact
const combined = {
  algorithm: [antTheme.darkAlgorithm, antTheme.compactAlgorithm],
};

See examples/core.md for dark mode toggle with persistence and algorithm combining.

Pattern 4: Layout System

Use Layout for page-level structure, Grid (Row/Col) for responsive content areas, Flex for inline element alignment, Space for uniform gaps between sm