antd-style

Ant Design Style is an application-level CSS-in-JS solution built upon the Ant Design V5 Token System. It provides a robust styling infrastructure for modern React applications, enabling seamless integration with Ant Design's design tokens.

Key capabilities include:

• Engine Compatibility: Works with multiple styling engines like styled-components and emotion-styled.
• Theme Management: Built-in support for easy light/dark mode switching using Ant Design V5's dynamic theme configuration.
• Customizable Themes: Allows for extending Ant Design's default tokens with custom tokens and custom stylish definitions.
• Stylish (Composite Styles): A utility for composing complex interactive styles by combining multiple atomic tokens, similar in philosophy to Tailwind CSS but with explicit design semantics.
• Responsive Design: Provides utility functions to simplify responsive theme development.
• Migration Support: Facilitates low-cost migration from legacy less setups to CSS-in-JS.
• Micro-frontend Compatibility: Compatible with qiankun micro-application architectures.

antd-style is a business-level CSS-in-JS solution designed specifically for applications and component libraries built on top of Ant Design V5. It is built upon the Ant Design V5 Token System and provides a secondary encapsulation of emotion to simplify styling workflows.

Key Use Cases

• Business Applications: Integrating Ant Design's theme tokens into your application's custom styles.
• Component Libraries: Building secondary component libraries that are based on Ant Design and need to consume its design tokens.

Comparison with @ant-design/cssinjs

While @ant-design/cssinjs is optimized for the internal implementation of the Ant Design component library itself (prioritizing performance via a specialized syntax), antd-style is optimized for developer experience (DX) and ease of use for application developers. Unlike the internal library, antd-style provides built-in capabilities to easily consume the Ant Design token system.

antd-style is a business-grade css-in-js solution built on top of emotion and integrated with the Ant Design V5 Token System.

Key capabilities include:

• Token System Integration: Seamlessly consumes Ant Design V5 tokens for easy style customization.
• Dark Mode Switching: Built-in support for easy light/dark theme switching using Ant Design's dynamic theme configuration.
• Custom Theme Extension: Ability to define custom tokens and 'Stylish' patterns when default Ant Design tokens are insufficient.
• Micro-app Compatibility: Default compatibility with qiankun micro-apps (with performance optimization options available for non-micro-app scenarios).
• Responsive Design: Provides utility functions to simplify responsive theme development.
• Stylish: A capability to compose complex interaction styles by combining multiple atomic tokens.
• Less Migration: Facilitates low-cost migration from legacy less projects to css-in-js.

The current implementation of antd-style uses emotion and @emotion/styled as its underlying engines, but they are utilized differently depending on the syntax:

css syntax

antd-style uses emotion for the css method. This was chosen because emotion supports converting the css API directly into class names, which is a requirement for the library's functionality. styled-components was ruled out because its css method lacks this capability.

styled syntax

antd-style uses @emotion/styled for the styled syntax. While styled-components offers native support for using components as selectors, @emotion/styled was chosen to keep the package size smaller (avoiding an additional ~10KB+).

Note on Component Selectors: If you require component selector syntax (often used for complex animations or compound selectors), antd-style recommends using the createStyles syntax instead, which is more natural and user-friendly for those scenarios.

:::info{title=Special Note} antd-style does not include the styled method by default. It only integrates @emotion/react's ThemeContext. To use the styled syntax, you must follow the integration guide: Integration with styled. :::

The getStaticInstance method in ThemeProvider is used to bridge the gap between React's context-based theme system and non-React code.

Inside the ThemeProvider, you use hooks like message.useMessage() to obtain a themed instance and a contextHolder. You then pass that instance back to the getStaticInstance callback. This effectively 'exposes' the themed instance to the outside world.

import { message } from 'antd';

const Provider = ({ getStaticInstance, children, theme }) => {
  // 1. Use useMessage to obtain the themed instance
  const [messageInstance, messageContextHolder] = message.useMessage();

  useEffect(() => {
    // 2. Use getStaticInstance to expose the instance to non-React environments
    getStaticInstance?.({
      message: messageInstance,
    });
  }, [messageInstance, getStaticInstance]);

  return (
    <ConfigProvider theme={theme}>
      {/* 3. Insert the context holder to render the message component */}
      {messageContextHolder}
      {children}
    </ConfigProvider>
  );
};

It is important to distinguish between a Style Engine and a Style Practice to understand how antd-style fits into your architecture:

1. Style Engine: The underlying library that handles the actual CSS-in-JS logic (e.g., emotion, styled-components, goober). These are tools for expanding style capabilities.
2. Style Practice: A solution that provides best practices, unified writing methods, and deterministic patterns for business applications (e.g., BEM, Tailwind CSS, or antd-style).

antd-style is a Style Practice library. It encapsulates high-quality CSS-in-JS engines to provide a unified, concise, and user-friendly syntax for common scenarios like application styles, component styles, responsive design, and dynamic/custom themes. Because it is a practice layer, it is designed to be decoupled from specific engines, allowing for future transitions to other technologies (like Atomic CSS-in-JS) without changing your standard antd-style API usage.