How to Customize Ant Design Theme Using Design Tokens: A Complete Guide

Use the ConfigProvider component to override specific design tokens in the theme.token object, which merges your custom values with Ant Design's default seed tokens to generate derived colors, spacing, and motion values across all components.

Ant Design's theming system revolves around design tokens—a hierarchical, type-safe architecture that transforms primitive seed values into comprehensive UI styling. Whether you're adjusting the primary brand color or disabling motion globally, understanding how to customize Ant Design theme using design tokens allows you to maintain visual consistency across the ant-design/ant-design component library without writing custom CSS.

Understanding Ant Design's Design Token Architecture

Seed Tokens and the Transformation Pipeline

The theming engine in components/theme/themes/default/index.ts generates the full token map from seed tokens—primitive values like colorPrimary and borderRadius. These seeds feed into transformation algorithms that produce derived values for backgrounds, text, borders, and motion.

The MapToken Interface and Type Safety

All generated tokens conform to the MapToken interface declared in components/theme/interface/maps/index.ts. This interface aggregates seed tokens, color palettes, size scales, font metrics, and motion timing into a single type-safe structure that components consume via the CSS-in-JS runtime.

How to Customize Ant Design Theme Using Design Tokens

Overriding Seed Tokens with ConfigProvider

The ConfigProvider component in components/config-provider/index.tsx merges your custom token object with the generated defaults. Override seed tokens to change fundamental aspects like brand color and global border radius:

import React from 'react';
import { Button, ConfigProvider, Space } from 'antd';

const App = () => (
  <ConfigProvider
    theme={{
      token: {
        // Seed token – changes the primary brand color
        colorPrimary: '#00b96b',
        // Seed token – adjusts the global border radius
        borderRadius: 2,
        // Derived token – fine-tunes specific backgrounds
        colorBgContainer: '#f6ffed',
      },
    }}
  >
    <Space>
      <Button type="primary">Primary</Button>
      <Button>Default</Button>
    </Space>
  </ConfigProvider>
);

export default App;

Customizing Derived and Motion Tokens

Beyond visual styles, you can control animation timing through motion tokens. Set motion: false to disable animations globally, or adjust specific duration tokens:

<ConfigProvider
  theme={{
    token: {
      motion: false,               // disables motion globally
      motionDurationFast: '0ms',   // explicit duration override
    },
  }}
>
  {/* Your application components */}
</ConfigProvider>

Extending the Token Map with Custom Values

For projects requiring custom tokens not included in the standard MapToken interface, extend the TypeScript definitions and inject values through ConfigProvider:

// Extend the token definition (TypeScript)
declare module 'antd/es/config-provider' {
  interface ThemeToken {
    myCustomColor?: string;
  }
}

// Usage
<ConfigProvider
  theme={{
    token: { myCustomColor: '#ff5722' },
  }}
>
  <div
    style={{
      // The CSS-in-JS runtime injects this as --myCustomColor
      backgroundColor: 'var(--myCustomColor)',
    }}
  >
    Custom colored box
  </div>
</ConfigProvider>

Switching Between Theme Algorithms

Ant Design provides built-in algorithms for default, dark, and compact themes. Import these from components/theme/interface/index.ts and apply them via the algorithm property:

import { ConfigProvider, theme } from 'antd';
import { useState } from 'react';

const ThemeSwitcher = () => {
  const [algorithm, setAlgorithm] = useState(theme.defaultAlgorithm);

  return (
    <ConfigProvider
      theme={{
        algorithm,                      // default, dark, or compact
        token: { colorPrimary: '#1890ff' },
      }}
    >
      {/* Your application UI */}
    </ConfigProvider>
  );
};

Summary

• Design tokens in Ant Design form a hierarchical system where seed tokens automatically propagate to derived values through algorithms in components/theme/themes/default/index.ts.
• Use ConfigProvider to override tokens at the application level; your custom values merge with defaults in components/config-provider/index.tsx.
• The MapToken interface in components/theme/interface/maps/index.ts ensures type safety across all customizable properties.
• You can disable motion globally, extend tokens with custom TypeScript definitions, or switch between default, dark, and compact algorithms without writing custom CSS.

Frequently Asked Questions

What are design tokens in Ant Design?

Design tokens are the atomic values—colors, spacing, fonts, and motion timing—that define Ant Design's visual language. According to the ant-design/ant-design source code, these start as seed tokens (like colorPrimary) in components/theme/themes/default/index.ts and expand into a full MapToken set that components consume via CSS-in-JS.

How do I disable all animations in Ant Design?

Set the motion token to false in your ConfigProvider theme configuration. As implemented in components/config-provider/index.tsx, this boolean disables all motion-related CSS transitions and animations across the component library. You can also set specific duration tokens like motionDurationFast to '0ms' for granular control.

Can I add custom design tokens not included in Ant Design?

Yes. You can extend the ThemeToken interface using TypeScript module augmentation and pass custom values through ConfigProvider. The CSS-in-JS runtime in ant-design/ant-design injects these as CSS custom properties (variables) prefixed with --, allowing you to reference them in inline styles or styled components while maintaining type safety.

Where are the default theme tokens defined in the source code?

The default theme generation logic resides in components/theme/themes/default/index.ts, which defines the algorithm that transforms seed tokens into the full derived palette. The resulting token structure conforms to the MapToken interface declared in components/theme/interface/maps/index.ts, ensuring consistency across the library's theming system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}