theming & design tokens

53 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Primary brand color

The primary brand color is #1677FF (blue). It was chosen because blue reads as trustworthy and focused without the corporate flatness of a darker navy or the playfulness of a saturated cyan. It is the default brand color for actions, links, focus rings, selected navigation, and active tabs.

Semantic state colors

Ant Design includes four semantic state seed colors: success (#52C41A), warning (#FAAD14), error (#FF4D4F), and info (#1677FF).

Preset colors for tags and charts

The preset colors (blue, purple, cyan, green, magenta, red, orange, yellow, volcano, geekblue, gold, lime; pink is a deprecated alias of magenta in runtime tokens) are reserved for tags, charts, and categorical visualization. Never use preset colors for primary UI affordances. Use functional colors (success/warning/error/info) for status, and reserve primary for the single most important action on each screen.

Neutral text colors and alpha values

Neutral text and overlays in the runtime token system are expressed as rgba(0, 0, 0, α) rather than flat grey hex values to allow for natural blending when text sits above tinted surfaces. The four standard alpha steps are: 0.88 (primary text, exported as #1F1F1F), 0.65 (secondary text, #595959), 0.45 (tertiary/description text), and 0.25 (placeholder/disabled, #BFBFBF). The hex values in the design document are composited results on a white surface, suitable for static export targets that require hex; downstream consumers that support alpha should prefer the rgba() form from @ant-design/cssinjs.

Neutral surface colors

Ant Design defines three neutral surface colors: surface (#FFFFFF) for content containers like cards, panels, tables, and forms; surface-container (#FAFAFA) for intermediate surfaces; and surface-layout (#F5F5F5) for page backgrounds.

4 px grid and spacing scale

All spacing snaps to a 4 px grid. The six-step spacing scale includes: unit (4px), xs (4px), sm (8px), md (16px), lg (24px), xl (32px). The control-height token is 32px. Magic numbers do not appear in token-driven code.

Three-layer surface model

Ant Design uses a three-layer surface model: bg-layout (#F5F5F5) is the page background that surrounds and contains everything else; bg-container (#FFFFFF) is the surface for cards, panels, tables, and forms where most content lives; bg-elevated (#FFFFFF, same hex as bg-container) is the surface for modals, dropdowns, popovers, distinguished from bg-container not by color but by shadow. Never hard-code #FFF or #FAFAFA in product code; read the token. The three-layer model is what lets a dark-mode algorithm flip the surface ladder without breaking layouts.

Elevation and shadow tiers

Ant Design is flat-first, with shadows appearing only on surfaces that genuinely float above their context. Shadow tokens generated from colorShadow adapt across light and dark themes. Core tiers are: Tertiary (boxShadowTertiary, light raised-surface shadow: 0 1px 2px 0 rgba(0,0,0,0.05), 0 1px 6px -1px rgba(0,0,0,0.03), 0 2px 4px 0 rgba(0,0,0,0.03)); Popup (boxShadow and boxShadowSecondary, standard floating-layer shadow: 0 6px 16px 0 rgba(0,0,0,0.08), 0 3px 6px -4px rgba(0,0,0,0.12), 0 9px 28px 8px rgba(0,0,0,0.05)); Card (boxShadowCard, card-specific raised shadow with tighter spread); Directional drawer and overflow shadows (boxShadowDrawer*, boxShadowTabsOverflow*, specialized tokens for edge-attached surfaces and scroll affordances); Popover arrow (boxShadowPopoverArrow, used only for the small triangular pointer on tooltip and popover arrows).

Motion durations in Ant Design

Motion uses three durations: motionDurationFast (0.1 s) for state changes like hover and focus; motionDurationMid (0.2 s) for component-internal transitions like collapse and fade; motionDurationSlow (0.3 s) for surface-level changes like modal enter and drawer slide.

Motion easing functions

Ant Design provides pre-defined easing functions: motionEaseInOut, motionEaseOut, motionEaseIn, motionEaseOutBack, motionEaseOutCirc, and others. Do not pick a transition-timing-function arbitrarily. If the design need does not match an existing easing, use motionEaseInOut and move on.

Border radius scale

Ant Design border radius scale: none (0px), sm (2px), md (4px), DEFAULT (6px), lg (8px), xl (16px), full (9999px). The default corner radius is 6 px, round enough to read as modern and friendly but small enough that a 32-pixel-tall button still presents a clean, almost-rectangular silhouette suitable for dense forms.

Border radius by component class

By component class: Controls (button, input, select, dropdown trigger) use 6 px (rounded.DEFAULT); Surfaces (card, modal, drawer, notification) use 8 px (rounded.lg); Tags and small chips use 4 px (rounded.md); Tooltip and popover use 4 px (rounded.md). Full-pill (rounded.full, 9999 px) is reserved for circular avatars, badges, and dots, not for buttons or tags. Square (0 px) is reserved for tables and the inner edges of segmented controls.

Design do's: read surfaces from tokens

Do read surfaces from colors.surface, colors.surface-container, and colors.surface-layout. They reflect the three-layer model.

Design don't: hard-code surface colors

Do not hard-code #FFFFFF or #FAFAFA in product code. The hex is incidental; the role is what matters.

Design do's: use motionDurationMid

Do use motionDurationMid (0.2 s) for any component-level transition you cannot find a more specific token for.

Design don't: invent easing curves

Do not invent custom cubic-bezier curves. Use the named easings provided.

Design do's: reserve preset colors

Do reserve the preset color palette (blue through lime) for tags, charts, and categorical visualization.

Design don't: mint custom accent colors

Do not mint accent colors outside the preset palette for one-off UI surfaces. If a screen seems to need one, the design probably needs a different layout instead.

Design do's: snap to 4 px grid

Do snap every gap, inset, and gutter to the 4 px grid through the spacing scale.

Design don't: use magic numbers

Do not use magic numbers in product code. If the scale lacks a step you need, the design needs revisiting, not a one-pixel override.

Theming via ConfigProvider theme prop

The primary theme configuration entry is ConfigProvider's theme prop, which accepts: (1) Seed token overrides via theme.token to replace any seed (primary and semantic color seeds expand into derived gradients, colorBgBase and colorTextBase drive neutral surfaces and text, spacing and radius and font-size seeds work the same way); (2) Algorithm switching via theme.algorithm to swap derivation logic (defaultAlgorithm, darkAlgorithm, and compactAlgorithm can be used alone or composed as an array); (3) Component-level overrides via theme.components.Button (or any component's token namespace) to override a single component's tokens without affecting others; (4) Runtime scope for dynamic theme switching by changing ConfigProvider.theme, with nested ConfigProvider instances creating local themes; (5) Token consumption and output via theme.useToken() inside React, theme.getDesignToken() outside React, theme.cssVar for CSS variables, and theme.zeroRuntime for prebuilt or extracted CSS.

Custom theme generation guidance

For custom theme generation, keep Ant Design's interaction structure, density, state feedback, and component semantics first. Then change the smallest necessary seed set: usually colorPrimary, status colors, borderRadius, fontFamily, fontSize, and neutral surface bases. Brand pages may look distinct, but forms, tables, navigation, overlays, focus states, and validation feedback should still feel like Ant Design. Avoid generating custom CSS rules that bypass tokens, algorithms, theme.components, CSS variables, or extracted static styles; if a theme cannot be expressed through those official layers, treat that as a design-system extension rather than a one-off page style.

Static API context limitation

Static APIs such as message.xxx, Modal.xxx, and notification.xxx do not automatically receive the surrounding ConfigProvider context. Use hook-based APIs, App, or explicit context holders when themed static feedback is required.

Input disabled border color uses colorBorderDisabled token

The Input component's disabled state should use the colorBorderDisabled design token for its border color. This was fixed in version 6.3.6 with PR #57518.

Tooltip maxWidth design token

Tooltip adds maxWidth design token. This was added in version 6.2.0 with PR #56540.

Theme zeroRuntime mode in ConfigProvider

ConfigProvider `theme` prop now supports `zeroRuntime` mode to avoid runtime style generation.

Design Token cssVar export in useToken

Design Token now exports `cssVar` in the `useToken` hook.

CSS variables used by default in theming

Ant Design now uses CSS variables by default for theming.

ConfigProvider focusOutline theme token for unified focus styles

Version 6.6.0 added the ConfigProvider theme token `focusOutline` to uniformly control focus outline styling across Input, Select, Rate, Steps, Splitter and other components.

Alert borderRadius component token

Version 6.6.0 added the `borderRadius` component token to Alert to customize border radius.

Design token heading font size supports string values

Version 6.4.0 fixed an issue where Design Token heading font size values did not support string type values.

ColorErrorAffix design token for input suffix error color

Version 6.4.0 added the `colorErrorAffix` Design Token to control the error state color of input field suffixes.

ColorWarningAffix design token for input suffix warning color

Version 6.4.0 added the `colorWarningAffix` Design Token to control the warning state color of input field suffixes.

Badge paddingInline design token

Version 6.4.0 added the `paddingInline` Design Token to Badge.

Collapse headerPaddingSM headerPaddingLG contentPaddingSM contentPaddingLG tokens

Version 6.5.0 added `headerPaddingSM`, `headerPaddingLG`, `contentPaddingSM` and `contentPaddingLG` tokens to Collapse to configure padding for small and large sizes.

ConfigProvider supports Modal and Drawer maskClosable global config

ConfigProvider now supports setting the `maskClosable` property globally for Modal and Drawer components, allowing control over whether the mask can be clicked to close these components.

ConfigProvider supports DatePicker and TimePicker suffixIcon global config

ConfigProvider now supports global configuration of the `suffixIcon` property for DatePicker and TimePicker components.

ConfigProvider supports Cascader expandIcon and loadingIcon global config

ConfigProvider now supports global configuration of `expandIcon` and `loadingIcon` properties for Cascader component.

ConfigProvider supports Table scroll global config

ConfigProvider now supports global configuration of the `scroll` property for Table component.

ConfigProvider supports Button loadingIcon global config

ConfigProvider now supports global configuration of the `loadingIcon` property for Button component.

ConfigProvider supports Form tooltipIcon and tooltipProps global config

ConfigProvider now supports global configuration of `tooltipIcon` and `tooltipProps` properties for Form component.

Tooltip adds maxWidth design token

Tooltip component now has a `maxWidth` design token available for configuration.

ConfigProvider supports pagination totalBoundary and showSizeChanger

ConfigProvider now supports global configuration of `pagination.totalBoundary` and `pagination.showSizeChanger` properties.

ConfigProvider supports Alert global icon configuration

ConfigProvider now supports configuring Alert component icons globally.

Breadcrumb supports separator global configuration

Breadcrumb component now supports global configuration of the `separator` property through ConfigProvider.

ConfigProvider supports Modal okButtonProps and cancelButtonProps

ConfigProvider now supports global configuration of Modal's `okButtonProps` and `cancelButtonProps` properties.

ConfigProvider theme supports zeroRuntime

ConfigProvider's `theme` configuration now supports `zeroRuntime` option to bypass CSS-in-JS style generation.

CSS-in-JS supports autoPrefixTransformer configuration

CSS-in-JS now supports configuring `autoPrefixTransformer` to add browser style prefixes automatically.

useToken hook exposes CSS variables

The `useToken()` hook now exposes CSS variables for consumption.

Design Token colorBorderDisabled added

A new `colorBorderDisabled` design token has been added to standardize border color for disabled states across components.

CSS variables enabled by default

CSS variables are now enabled by default in Ant Design 6.0.0.

Color components support preset color names

Color-related components now support preset color names such as 'red', 'blue', 'green', etc.

ConfigProvider supports tooltip.unique for smooth Tooltip movement

ConfigProvider now supports `tooltip.unique` configuration enabling Tooltip to move smoothly without closing and reopening.

Give your agent this brain