Design Token Architecture

Source: ant.design/docs/react/customize-theme

Ant Design 5.x uses a three-layer algorithmic token architecture. The key insight is that changing a small number of "seed" values automatically propagates through a derivation algorithm to update dozens of dependent tokens — making system-wide visual changes low-effort and consistent.

Three-layer architecture

Seed Tokens
    ↓ (algorithm)
Map Tokens
    ↓ (aliasing)
Alias Tokens
    ↓
Component Tokens

Seed Tokens

High-level design intentions — the inputs you control. Examples:

Seed Token	Default	What it controls
`colorPrimary`	`#1677ff`	Brand color; drives all primary interactive states
`colorSuccess`	`#52c41a`	Success state color
`colorWarning`	`#faad14`	Warning state color
`colorError`	`#ff4d4f`	Error / danger color
`colorInfo`	`#1677ff`	Informational color
`borderRadius`	`6`	Base border-radius; drives SM/LG/XS variants
`fontSize`	`14`	Base font size; drives heading scale
`motion`	`true`	Enable / disable all animations

Most customization needs can be met at the seed level alone.

Map Tokens

Derived values computed algorithmically from seed tokens. You generally do not set these directly — they are calculated from seed inputs via the preset algorithm. They represent the full expanded token vocabulary: hover colors, active colors, disabled states, border variants, etc.

Alias Tokens

Named references to map tokens, used as the actual values in component styles. For example, colorText is an alias that points to a specific map token for primary text. You can override alias tokens when you need to break the derivation pattern for specific roles.

ConfigProvider

All token customization is applied through the <ConfigProvider> component:

import { ConfigProvider } from 'antd';

function App() {
  return (
    <ConfigProvider
      theme={{
        token: {
          colorPrimary: '#your-brand',
          borderRadius: 4,
          fontSize: 14,
        },
      }}
    >
      <YourApp />
    </ConfigProvider>
  );
}

Limitation: Static methods (message.success(), Modal.confirm(), notification.open()) do not inherit ConfigProvider context. Use Modal.useModal() or wrap with the App component from antd.

Preset algorithms

Ant Design ships three built-in derivation algorithms:

Algorithm	Effect
`theme.defaultAlgorithm`	Standard light appearance — the default
`theme.darkAlgorithm`	Dark mode — recalculates all derived tokens for dark surfaces
`theme.compactAlgorithm`	Compact density — reduces `controlHeight` and spacing proportionally

Algorithms can be combined:

import { theme } from 'antd';

<ConfigProvider
  theme={{
    algorithm: [theme.darkAlgorithm, theme.compactAlgorithm],
  }}
>

Component-level tokens

Override tokens for a specific component without affecting others:

<ConfigProvider
  theme={{
    components: {
      Button: {
        colorPrimary: '#custom-color',
        borderRadius: 2,
        algorithm: true,  // re-derive hover/active from this seed
      },
      Table: {
        colorBgContainer: '#fafafa',
      },
    },
  }}
>

Setting algorithm: true on a component token tells the system to re-run the derivation algorithm from the overridden seed rather than using the static value directly.

Consuming tokens in components

import { theme } from 'antd';

const MyComponent = () => {
  const { token } = theme.useToken();

  return (
    <div style={{
      color: token.colorText,
      background: token.colorBgContainer,
      borderRadius: token.borderRadius,
      padding: `${token.paddingMD}px ${token.paddingLG}px`,
    }}>
      ...
    </div>
  );
};

For static contexts outside React lifecycle:

const globalToken = theme.getDesignToken();

Full token vocabulary

Color tokens

Category	Key tokens
Semantic	`colorPrimary`, `colorSuccess`, `colorWarning`, `colorError`, `colorInfo`
Text	`colorText`, `colorTextSecondary`, `colorTextTertiary`, `colorTextQuaternary`, `colorTextDisabled`
Background	`colorBgContainer`, `colorBgElevated`, `colorBgLayout`, `colorBgMask`
Border	`colorBorder`, `colorBorderSecondary`, `colorBorderDisabled`
Fill	`colorFill`, `colorFillSecondary`, `colorFillTertiary`, `colorFillQuaternary`

Size tokens

Token	Default	Meaning
`controlHeight`	32	Default control height (input, button)
`controlHeightLG`	40	Large control height
`controlHeightSM`	24	Small control height
`controlHeightXS`	16	Extra-small control height
`fontSize`	14	Base font size

Spacing tokens

Margin and padding tokens use size suffixes: XXS, XS, SM, MD (base), LG, XL, XXL.

Example: token.marginMD (base margin), token.paddingLG (large padding).

Radius tokens

Token	Default
`borderRadius`	6
`borderRadiusLG`	8
`borderRadiusSM`	4
`borderRadiusXS`	2

Motion tokens

Token	Default	Meaning
`motion`	`true`	Enable / disable all animations
`motionUnit`	`0.1`	Duration increment (seconds)
`motionBase`	`0`	Base duration offset
`motionEaseInOut`	`cubic-bezier(0.645, 0.045, 0.355, 1)`	Standard easing
`motionEaseOutBack`	`cubic-bezier(0.12, 0.4, 0.29, 1.46)`	Overshoot easing

Shadow tokens

Token	Usage
`boxShadow`	Primary elevation (popovers, dropdowns)
`boxShadowSecondary`	Secondary elevation
`boxShadowTertiary`	Subtle elevation

Breakpoints

Token	px value
`screenXS`	480
`screenSM`	576
`screenMD`	768
`screenLG`	992
`screenXL`	1200
`screenXXL`	1600

Nested themes

Nest ConfigProvider components to apply localized themes to sections of the UI. Child themes inherit all unmodified parent tokens — only explicitly overridden tokens change:

<ConfigProvider theme={{ token: { colorPrimary: '#blue' } }}>
  <MainContent />
  <ConfigProvider theme={{ token: { colorPrimary: '#red' } }}>
    <DangerZone />  {/* red primary, all other tokens inherited from parent */}
  </ConfigProvider>
</ConfigProvider>

Architecture comparison

System	Token layers	Derivation model
Ant Design 5.x	Seed → Map → Alias → Component	Algorithmic — seed drives derivatives
Material 3	Reference → System → Component	Algorithmic (HCT tonal palettes)
Carbon	Primitive → Semantic	Manual mapping, no algorithm
Atlassian	All-semantic (no primitive exposed)	Manual, role + emphasis + state naming
Radix Themes	Config props → CSS variables	Config-first, no traditional token vocabulary

Design Tokens