ant-design

ant-design Best Practices

This guide outlines the definitive best practices for using Ant Design v6.x in our projects. Adhering to these standards ensures consistency, accessibility, and maintainability across our codebase.

1. Theming: Design Token Driven

Always customize Ant Design's appearance using its design token system via ConfigProvider. Avoid direct CSS overrides for visual properties that can be controlled by tokens.

✅ GOOD: Centralized Token Customization

Create a theme.ts file to export your theme configuration and apply it at the root of your application. Prefer seedToken adjustments for global changes and componentToken for specific component overrides. Utilize preset algorithms for light/dark mode.

// src/theme.ts
import { theme } from 'antd';
import type { ThemeConfig } from 'antd';

export const appTheme: ThemeConfig = {
  algorithm: theme.defaultAlgorithm, // Or theme.darkAlgorithm, [theme.defaultAlgorithm, theme.darkAlgorithm]
  token: {
    colorPrimary: '#0050B3', // Our primary brand color
    colorSuccess: '#52C41A',
    fontSize: 14,
    borderRadius: 4,
    // Disable motion globally for accessibility/performance
    motion: false,
  },
  components: {
    Button: {
      colorPrimary: '#1890FF', // Override primary button color
      algorithm: true, // Enable algorithm for component token derivation
    },
    Layout: {
      headerBg: '#001529',
      footerBg: '#F0F2F5',
    },
  },
};

// src/App.tsx (or root layout)
import React from 'react';
import { ConfigProvider, App as AntdApp } from 'antd';
import { appTheme } from './theme';
import HomePage from './pages/HomePage';

const App: React.FC = () => {
  return (
    <ConfigProvider theme={appTheme}>
      {/* Use AntdApp for context-aware static methods (message, Modal, notification) */}
      <AntdApp>
        <HomePage />
      </AntdApp>
    </ConfigProvider>
  );
};

export default App;

❌ BAD: Direct CSS Overrides

Avoid overriding Ant Design component styles with custom CSS classes or inline styles for properties that are themeable. This leads to inconsistent UIs and breaks theme updates.