theming/design tokens

64 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Component Token for component-specific style customization

Each component in Ant Design exposes its own Component Token to enable component-specific style customization capabilities. Different components do not influence each other through their Component Tokens. Component Tokens can also be used to override other Design Tokens consumed by a component.

Component token algorithm property in version 5.8.0+

In Ant Design version 5.8.0 and later, the component token supports passing the `algorithm` property, which enables derivative calculation or allows passing in other algorithms for token computation.

Disable all motion and animations globally

Ant Design includes built-in component interaction animations by default. To disable all animations globally in extreme scenarios where animations may affect page interaction performance, set the `motion` token to `false`.

Seed Tokens definition

Seed Tokens are theme variables that, when modified, cause changes to other theme variables. They are modified through the token property in the theme configuration.

Theme variable modification via token property

Theme variables can be modified through the token property in the theme object. Some of these theme variables are Seed Tokens that will cascade changes to other theme variables.

Switch themes with algorithm property

You can switch between theme algorithms by modifying the algorithm property in the theme configuration. Multiple algorithms can be configured together and they will take effect in the order specified.

useToken hook for accessing design tokens

The useToken hook is provided to get Design Tokens of the current theme in React.

Alias Token definition and purpose

Alias Tokens are used to control the style of common components in batches. They are essentially Map Token aliases or specially processed Map Tokens that provide convenient references for styling related components together.

Three-layer design token structure

Ant Design uses a three-layer Design Token structure: Seed Token (origin of design intent), Map Token (derived from Seed Token), and Alias Token (derived from Map Token). Each layer has a derivation relationship where higher layers depend on lower layers.

useToken hook for consuming design tokens

Use the useToken hook provided by Ant Design to get Design Tokens under the current theme. This allows consuming design tokens within React components.

Static getDesignToken function

When you need design tokens outside of React lifecycle, use the static function getDesignToken() from the theme module. Example: import { theme } from 'antd'; const { getDesignToken } = theme; const globalToken = getDesignToken(); This can also accept a config object as a parameter.

Seed Token definition and purpose

Seed Tokens represent the origin of all design intent in Ant Design. They are the starting point for theme customization. For example, changing colorPrimary will trigger antd's internal algorithm to automatically calculate and apply a series of corresponding colors based on that Seed Token.

Static Design Token consumption with getDesignToken

The static method `getDesignToken` exported from 'antd' theme allows consuming token variables outside React lifecycle. It supports passing a `theme` property to retrieve Design Token for a specified theme. Import with `const { getDesignToken } = theme`.

Seed Token, Map Token, and Alias Token three-layer structure

Design Token is structured in three layers: Seed Token (the origin of design intent), Map Token (derivative variables based on Seed Token), and Alias Token (for controlling shared component styles, typically Map Token aliases or specially processed Map Token). This creates a derivation relationship: Seed Token derives Map Token, which derives Alias Token.

Seed Token example: colorPrimary

Seed Token represents the source of all design intent. For example, changing `colorPrimary` changes the theme color. Ant Design's internal algorithm automatically calculates a series of corresponding colors based on the Seed Token and applies them: `const theme = { token: { colorPrimary: '#1890ff' } };`

Map Token definition and modification

Map Token is a gradient variable derived from Seed Token. Customizing Map Token is recommended through `theme.algorithm` to maintain gradient relationships between Map Token values. Individual Map Token values can also be overridden through `theme.token`: `const theme = { token: { colorPrimaryBg: '#e6f7ff' } };`

Alias Token for shared component control

Alias Token is used for batch control of shared component styles. It is basically a Map Token alias or specially processed Map Token: `const theme = { token: { colorLink: '#1890ff' } };`

Algorithm for expanding Seed Token to Map Token

Algorithms convert Seed Token into Map Token, such as calculating a gradient color palette from a base color or calculating various border radius sizes from a base radius. Algorithms can be used independently or combined: `const theme = { algorithm: [darkAlgorithm, compactAlgorithm] };`

Theme API: token property

The `token` property in Theme configuration is of type `AliasToken` and is used to modify Design Token. It has no default value and is not version-specific.

Theme API: inherit property

The `inherit` property in Theme configuration is of type boolean with a default value of `true`. It controls whether to inherit the theme configured in the parent ConfigProvider.

Theme API: algorithm property

The `algorithm` property in Theme configuration is of type `(token: SeedToken) => MapToken` or `((token: SeedToken) => MapToken)[]`. It modifies the algorithm that converts Seed Token to Map Token. The default value is `defaultAlgorithm`.

Theme API: components property

The `components` property in Theme configuration is of type `ComponentsConfig` and is used to modify Component Token and override Alias Token consumed by each component. It has no default value.

Theme API: cssVar property

The `cssVar` property in Theme configuration controls CSS variable settings. It has no default value and is not version-specific.

Theme API: hashed property

The `hashed` property in Theme configuration is of type boolean with a default value of `true`. It controls whether to add styles to hashed className.

Theme API: zeroRuntime property

The `zeroRuntime` property in Theme configuration is of type boolean with a default value of `false`, introduced in version 6.0.0. When enabled, zero runtime mode prevents style generation at runtime, requiring manual CSS file import.

ComponentsConfig structure for component theming

ComponentsConfig allows modification of Component Token and override of Alias Token consumed by components. Each property name can be any antd component name (like `Button`). The value type is `ComponentToken & AliasToken & { algorithm: boolean | (token: SeedToken) => MapToken | ((token: SeedToken) => MapToken)[] }`. Component-level `algorithm` defaults to `false`, only overriding tokens used by that component without derivation calculation. Setting it to `true` inherits the current global algorithm, or pass one or more algorithms to override the global algorithm for that component.

cssVar configuration: prefix property

The `prefix` property in cssVar configuration is of type string with a default value of `ant`. It sets the prefix for CSS variables, defaulting to the `prefixCls` configured on ConfigProvider.

cssVar configuration: key property

The `key` property in cssVar configuration is of type string with a default value of `useId` in React 18. It provides a unique identifier key for the current theme.

Theme undefined to object remounting issue and solution

When `theme` changes from `undefined` to an object or vice versa in ConfigProvider, components remount because `undefined` theme does not wrap a Provider layer, causing React's VirtualDOM structure to change. Solution: replace `undefined` with an empty object `{}`.

Less loader integration with Design Token

To apply Design Token to static style compilation frameworks like less, use less-loader injection: `{ loader: 'less-loader', options: { lessOptions: { modifyVars: mapToken } } }`. Compatibility package provides variable conversion methods to convert to v4 less variables.

Static style extraction with @ant-design/static-style-extract

The @ant-design/static-style-extract package allows generating static styles for specific components. Example usage: `const { extractStyle } = require('@ant-design/static-style-extract'); const cssText = extractStyle({ includes: ['Button'] });` generates styles only for the Button component.

Theme editor tool availability

Ant Design provides a theme editor tool at /theme-editor-cn to help debug themes. Users can freely modify Design Token to achieve their desired theme.

Design Token definition and purpose

Design Token is the minimal element that affects the theme in Ant Design. By modifying Design Token, you can present various themes or components. Design Token is passed through the `theme` property in `ConfigProvider`.

Theme capabilities since version 5.0

Since version 5.0, Ant Design provides a new theming solution powered by CSS-in-JS. The capabilities include: dynamic theme switching, simultaneous existence of multiple themes, and modifying theme variables for specific components.

ConfigProvider limitation with static methods

ConfigProvider does not take effect on static methods like `message.xxx`, `Modal.xxx`, and `notification.xxx` because antd creates new React entities dynamically through `ReactDOM.render` in these methods, and their context differs from the current code context. To use context information, call `Modal.useModal` to get the modal entity and contextHolder node, then insert it at the location where context is needed, or use the App wrapper component to simplify the process.

Three preset algorithms available

Ant Design provides three preset theme algorithms: defaultAlgorithm (the default), darkAlgorithm (dark theme), and compactAlgorithm (compact theme). Switch between algorithms using the `algorithm` property in `theme`, and multiple algorithms can be configured to take effect in order.

Component Token for component-specific theming

Component Token allows style customization for individual components without affecting others. Different components expose their own Component Token. Component-level theme algorithm is supported in version >= 5.8.0, allowing derivation calculation or passing other algorithms.

Disable animation in theme configuration

To disable animations, set `motion` to `false` in the `token` configuration within the theme. By default, antd includes component interaction animations to enrich enterprise-level pages, but these may affect page interaction performance in extreme scenarios.

zeroRuntime mode performance optimization

Since version 6.0.0, Ant Design provides `zeroRuntime` mode to improve application performance. When enabled, Ant Design no longer generates component styles at runtime, requiring manual import of style files. Import 'antd/dist/antd.css' to include all component styles. For custom configurations or to include fewer styles, use the @ant-design/static-style-extract package to generate static styles.

Dynamic theme switching

In version 5, dynamic theme switching is simple: modify the `theme` property of `ConfigProvider` at any time without additional configuration.

Local theme with nested ConfigProvider

Nest `ConfigProvider` components to implement local theme changes. Design Token values not changed in child themes inherit from the parent theme.

useToken hook for accessing Design Token

Use the `useToken` hook to access the Design Token of the current theme. This hook retrieves the current theme's Design Token values.

Relationship between colorPrimary, colorInfo, and colorLink in V5

In the Ant Design Token system, colorPrimary and colorInfo are both Seed Tokens and are independent of each other. colorLink is an Alias Token that inherits colorInfo by default and is independent of colorPrimary.

Disable motion in antd

To disable motion/animations in antd, configure the motion SeedToken to false: <ConfigProvider theme={{ token: { motion: false } }}><App /></ConfigProvider>

Relationship between colorPrimary, colorInfo, and colorLink tokens

colorPrimary and colorInfo are both Seed Tokens (base variables) and are independent of each other. colorLink is an Alias Token (alias variable) that by default inherits from colorInfo and is not related to colorPrimary.

Neutral color palette definition

The neutral color palette definition in Ant Design is balanced with readability, aesthetics and usability. Neutral color definition needs to consider the difference between dark background and light background, while incorporating the WCAG 2.0 standard. The neutral color of Ant Design is based on transparency.

Color palette tool for custom generation

If the predefined color palettes do not meet specific needs, designers and developers can select a primary color and Ant Design's color generation algorithm will automatically generate a complete color palette based on that primary color.

Using Ant Design color palettes in code

Programmers can use Ant Design color palettes via JavaScript by installing the @ant-design/colors package (npm install @ant-design/colors). Usage example: import { blue } from '@ant-design/colors'; console.log(blue); returns ['#E6F4FF', '#BAE0FF', '#91CAFF', '#69B1FF', '#4096FF', '#1677FF', '#0958D9', '#003EB3', '#002C8C', '#001D66']. console.log(blue.primary); returns '#1677FF'. More usage details are available at npmjs.com/package/@ant-design/colors.

Ant Design brand color hex value and application

Ant Design's brand color is taken from the blue of the basic color palette with the hex value #1677FF. This is the sixth color from light to deep in the color palette. The recommended usage is to select the sixth color from the palette as the primary brand color. The brand color is applied in scenarios including key action points, operation states, important information highlighting, and graphic contexts.

Functional color usage principles

Functional colors represent clear information and states such as success, error, failure, warning, and links. Functional color selection must follow user's basic color cognition. Within one product system, functional colors should remain consistent with minimal customization to avoid disrupting user experience.

Neutral color application and WCAG 2.0 compliance

Ant Design's neutral colors are primarily applied to text in interfaces, and also frequently used for backgrounds, borders, and dividing lines. Product neutral color definition must consider differences between dark and light backgrounds and comply with WCAG 2.0 standards. Ant Design implements neutral colors using transparency methods in production.

Ant Design basic color palette size and structure

Ant Design's basic color palette consists of 120 colors total, including 12 primary colors and derived colors. These colors are derived from 12 core colors abstracted from natural scenes, combined with Ant Design's technical gene. The colors are further derived by observing how different colors change under natural light, using a technique similar to sketching in art.

Neutral color palette composition

Ant Design's neutral color palette contains black, white, and gray, comprising 13 colors in total ranging from white to black. These are widely used in ant enterprise middle platform web design to establish good information hierarchy and enhance reading experience.

Data visualization color palette source

The data visualization color palette is generated based on the basic color palette and neutral color palette, incorporating AntV's principles of effective, clear, accurate, and beautiful design. It is viewable at antv.antgroup.com/specification/language/palette.

Font color tokens

Ant Design provides design tokens for text colors including colorTextHeading, colorText, colorTextSecondary, colorTextDisabled, colorBorder, colorSplit, and colorBgLayout.

HiTu color palette foundation

The HiTu color system is based on Ant Design's color palette with scene-specific applications. While different from UI color system applications, HiTu's color system is more flexible and variable. Brightness levels were adjusted from the Ant Design base palette to expand the tolerance of graphic design and improve selection efficiency and ease of use. The color system maintains perfect compatibility with other UI assets.

HiTu default asset primary color selection

Research on enterprise products showed that blue and white are the most widely used colors. Geek Blue was selected as the primary color for HiTu's default assets because it conveys the most technological feel and represents exploration and research spirit.

Varying vertical spacing beyond three standard sizes

When the three standard vertical spacing sizes are not suitable, spacing can be adjusted by adding or subtracting multiples of the base spacing (8px), or by adding visual elements like dividers to create information hierarchy.

Vertical spacing scale: 8px, 16px, 24px

Ant Design uses three standard vertical spacing specifications to divide information hierarchy: small spacing (8px), medium spacing (16px), and large spacing (24px).

Vertical spacing formula in Ant Design

In Ant Design, vertical spacing is calculated using the formula y = 8 + 8 * n, where n >= 0, y is the vertical spacing, and 8 is the base spacing unit in pixels.

Give your agent this brain